vpsFree.cz development workspace extensions

This repository adds vpsFree.cz tools to the reusable aither64/dev-workspace runtime. It owns the KB commands, vpsAdmin, vpsAdminOS and optional KB cluster providers, Codex skills, and the one-time namespace migration helper.

The vpsAdmin development cluster guide documents its configuration, runtime credentials, and recovery steps. The managed KB cluster guide explains the optional provider and its connection to the standalone KB runtime. The workspace confctl adapter prepares and activates exact generations under the generic runtime's machine reservations.

The generic runtime supplies the dev-session-documentation skill. Its session guide explains document ownership and rationale capture. This extension connects that workflow to its review packets and handoffs; each consuming workspace names its project and site-specific documentation destinations.

The mandatory review skill owns final review routing. Invoke it for completed substantive deliverables, including standalone documentation and configuration changes, after commits and quick checks and before long integration tests. Routine planning, investigation, findings, session tracking and evidence alone cause no automatic review. Explicitly requested early review is advisory and does not replace final review. Solo sessions use a temporary independent reviewer without changing their roster.

Concrete endpoints, credential paths, and development-cluster defaults are not stored here. A consuming workspace passes them to lib.mkPackage:

vpsfree-dev-workspace.lib.mkPackage {
  inherit pkgs;
  siteConfig = {
    kb = {
      cz = {
        url = "https://kb-cz.example.test";
        tokenPath = "/credentials/kb-cz-token";
        stagingUrl = "https://kb-cz-staging.example.test";
        stagingPasswordPath = "/credentials/kb-cz-staging-password";
      };
      org = {
        url = "https://kb-org.example.test";
        tokenPath = "/credentials/kb-org-token";
        stagingUrl = "https://kb-org-staging.example.test";
        stagingPasswordPath = "/credentials/kb-org-staging-password";
      };
      stagingUsername = "developer";
      stageContainerctl = "/run/current-system/sw/bin/containerctl";
    };
    clusterDefaults = {
      vpsadmin = ./config/vpsadmin-devcluster.json;
      vpsadminos = ./config/vpsadminos-devcluster.json;
      # Optional: include the managed KB cluster provider.
      kb = ./config/kb-devcluster.json;
    };
  };
}

Each registered workspace keeps its portal identity and selected cluster providers in the .dev-workspace.json file at its own root. This extension exports vpsadmin and vpsadminos. Setting siteConfig.clusterDefaults.kb also exports kb; omitting it preserves the existing provider set. A workspace can select providers only while its package includes them.

Catalog composition

The installed extensions.json is a composed catalog: it contains the generic runtime's skills as well as this extension's site skills. Consumers and tests must require the vpsFree skills they need, without asserting an exact global skill list. The generic runtime currently supplies dev-session-documentation and dev-session-monitor, and it may add compatible foundational skills.

The vpsFree package must continue to provide dev-session-handoff, mandatory-change-review, and vpsfree-user-facing-writing alongside its other site skills. Its catalog must list the vpsadmin and vpsadminos providers, whose recorded commands and portal helper executables must be present in the installed package. When KB cluster defaults are configured, the catalog also lists kb and the package includes its fixed portable engine and public provider command.

The optional userNamespace and routerSocket arguments are passed to the generic package constructor. They are intended for a compatibility generation during the namespace migration; ordinary packages should keep the generic defaults.

Run the regular package and contract checks with:

nix flake check --print-build-logs

Check the installed development-cluster flakes and runner dependencies with:

nix run .#devcluster-check

This check uses locked test inputs and temporary configuration. It evaluates both network modes with package defaults and per-cluster overrides, then builds and loads both Ruby runners. It does not build VM closures or start VMs. Run it outside a Nix build sandbox so it can access the Nix daemon.

The migration helper is intentionally not automatic or linked into ~/bin. Invoke it through the package's private libexec/vpsfree-dev-workspace-migrate path, read its --help output and follow the namespace migration runbook. Retain its private journals until the deployed cutover has been accepted.

The local operator is trusted with host administration for workspace integration and namespace migration. Root/user ownership supports their operational lifecycle. Remote clients and guests remain untrusted, and KB publication still requires its existing approval process.

The Host migration workflow runs the NixOS migration smoke test when migration or local host-contract files change on master. After review, run the test locally on feature branches or when an upstream host-state compatibility change needs validation:

nix build --no-link --print-build-logs .#host-migration-test

Manual workflow dispatch is also available once the workflow exists on the default branch. Regular dependency updates retain the fast Ruby migration and host-path contract checks without booting this additional VM. CI requires KVM for the VM job and targets normal dependency-update completion within 20 minutes.