@treeseed/cli 0.10.21 → 0.11.0

package/README.md

@@ -1,174 +1,147 @@
-# `@treeseed/cli`
+# @treeseed/cli
 
-Operator-facing Treeseed CLI package.
+`@treeseed/cli` publishes the `treeseed` and `trsd` command surfaces. Use it to configure Treeseed, run local development, save/stage/release work, reconcile hosting, operate capacity providers, manage package images, and inspect workflow state.
 
-This package publishes the `treeseed` binary. `@treeseed/sdk` owns the reusable workflow and runtime capabilities, `@treeseed/core` owns integrated local platform orchestration, and `@treeseed/cli` owns argv parsing, command help, terminal formatting, command handlers, and the installable executable surface.
+The CLI is the human and automation entrypoint over package-owned capabilities. It delegates platform logic to `@treeseed/sdk`, web runtime orchestration to `@treeseed/core`, backend behavior to API surfaces, capacity runtime to `@treeseed/agent`, and TreeDX image workflows to package manifests.
 
-## Requirements
+## What You Can Do With The CLI
 
-- Node `>=22`
-- npm as the canonical package manager for install, CI, and release flows
+- configure local, staging, and production environments
+- start and inspect local development instances
+- save, stage, close, resume, and release multi-repo work
+- plan/apply/verify hosted infrastructure through reconciliation
+- run operations-runner smoke checks
+- build and operate capacity providers
+- manage TreeDX package image workflows
+- inspect package drift, workflow locks, and interrupted runs
 
 ## Install
 
-Install the CLI with its runtime dependencies:
-
 ```bash
-npm install @treeseed/cli @treeseed/core @treeseed/sdk
+npm install @treeseed/cli
 ```
 
-`@treeseed/cli` is a thin installable wrapper over `@treeseed/sdk` workflow and operations interfaces plus the Treeseed runtime packages. `treeseed dev` resolves the tenant-installed or sibling-workspace `@treeseed/core` web runtime, while `treeseed agents ...` delegates to `@treeseed/agent`. In normal consumer installs, npm resolves the runtime dependencies automatically.
-
-Workflow guarantees:
-
-- `treeseed` is the only supported project-management surface for market and any checked-out `packages/sdk`, `packages/core`, and `packages/cli` repos.
-- `treeseed switch` requires clean worktrees, mirrors the task branch into checked-out package repos, and only pushes the market branch on branch creation.
-- `treeseed save` is the canonical recursive checkpoint command: it verifies, commits, and pushes dirty package repos in dependency order before saving the market repo.
-- `treeseed stage` squash-merges task branches into `staging` across package repos first, refreshes market submodule pointers to package `staging` heads, then stages the market repo.
-- `treeseed close` recursively archives and deletes matching task branches across market and checked-out package repos.
-- `treeseed release` only bumps, tags, and publishes changed packages plus internal dependents, then syncs market production to package `main` heads.
-- Every mutating workflow command supports `--plan`; `--dry-run` is only an alias where it still exists for compatibility.
-- Interrupted workflow runs are journaled under `.treeseed/workflow`; use `treeseed recover` to inspect them and `treeseed resume <run-id>` to continue a resumable run.
-
-After installation, the published binary is available as:
+After installation:
 
 ```bash
 treeseed --help
+trsd --help
 ```
 
-## Primary Workflow
-
-The main workflow commands exposed by the current CLI are:
+In this workspace, use `npx trsd ...` from the root.
 
-- `treeseed status [--json]`
-- `treeseed config`
-- `treeseed tasks [--json]`
-- `treeseed switch <branch-name> [--preview]`
-- `treeseed dev`
-- `treeseed dev start|status|logs|stop|restart`
-- `treeseed save [--preview] [--plan] "<commit message>"`
-- `treeseed stage "<resolution message>"`
-- `treeseed close "<close reason>"`
-- `treeseed release --major|--minor|--patch [--plan]`
-- `treeseed resume <run-id>`
-- `treeseed recover`
-- `treeseed destroy --environment <local|staging|prod> [--plan]`
-
-Support utilities such as `treeseed rollback`, `treeseed doctor`, `treeseed auth:*`, `treeseed template`, `treeseed sync`, `treeseed lint`, `treeseed test`, `treeseed build`, service helpers, and `treeseed agents ...` remain available.
-
-Use `treeseed help` for the full command list and `treeseed help <command>` for command-specific usage, options, and examples.
-
-## Common Commands
+## Primary Commands
 
 ```bash
-treeseed status
-treeseed config
-treeseed switch feature/search-improvements --plan
-treeseed switch feature/search-improvements --preview
-treeseed dev
-treeseed dev start --web-runtime local
-treeseed save --preview "feat: add search filters"
-treeseed stage "feat: add search filters"
-treeseed release --patch
-treeseed recover
 treeseed status --json
+treeseed config
+treeseed ready local --json
+treeseed switch feature/my-change --plan --json
+treeseed dev start --web-runtime local --json
+treeseed save --verify local --json "describe the checkpoint"
+treeseed stage --plan --json "describe the staging change"
+treeseed release --patch --verify-deployed-resources --plan --json
+treeseed recover --json
 ```
 
-## Development Server Instances
-
-`treeseed dev` remains the foreground local runtime supervisor. It delegates to `@treeseed/core`, starts the Market web/API/control-plane development surface, streams output in the active terminal, and exits when the shell-owned process is stopped.
-
-Managed dev instances use subcommands:
+Hosted diagnostics:
 
 ```bash
-treeseed dev start --web-runtime local --json
-treeseed dev status --json
-treeseed dev status --all --json
-treeseed dev logs --follow
-treeseed dev stop --json
-treeseed dev restart --web-runtime local --json
+treeseed ready staging --json
+treeseed hosting plan --environment staging --service api --json
+treeseed hosting verify --environment staging --service operationsRunner --live --json
+treeseed operations smoke --environment staging --service operationsRunner --json
 ```
 
-Managed instances are scoped to the current physical worktree. The core runtime writes `.treeseed/dev/instances/<scope>.json`, `.treeseed/dev/pids/<scope>.pid`, and `.treeseed/logs/dev-<scope>.jsonl` in that worktree. A repository-family index under the git common dir makes sibling worktree instances discoverable to humans and AI agents.
-
-`--force` replaces only the current worktree instance. `--force-conflicts` is the explicit cross-worktree port-owner escape hatch. Additional worktrees receive stable alternate port blocks and worktree-specific local PostgreSQL/Mailpit names, so many agents can run development sessions in the same repository family.
-
-For the complete architecture, see the root workspace document `docs/local-dev-instances.md`.
-
-## Agent-Safe Workflow
-
-Use planning mode before any destructive or multi-repo mutation:
+Capacity providers:
 
 ```bash
-treeseed switch feature/search-improvements --plan --json
-treeseed save --plan "feat: add search filters" --json
-treeseed stage --plan "feat: add search filters" --json
-treeseed release --patch --plan --json
+treeseed capacity build
+treeseed capacity up
+treeseed capacity status
+treeseed capacity logs
+treeseed capacity down
 ```
 
-If a workflow stops partway through, inspect the journaled state and resume from the recorded run:
+TreeDX package image:
 
 ```bash
-treeseed recover
-treeseed resume <run-id>
+treeseed package image --package treedx --branch staging --plan --json
+treeseed package image --package treedx --branch staging --sync-config --json
+treeseed package image --package treedx --branch staging --execute --json
 ```
 
-In a full checked-out workspace, `treeseed tasks`, `treeseed status`, and `treeseed doctor` also report package-branch drift, dirty embedded repos, active workflow locks, and interrupted runs.
+Use `treeseed help <command>` for command-specific usage and examples.
 
-## Maintainer Workflow
+## Managed Package Set
 
-All package maintenance commands are npm-based and run from the `cli/` package root. This package verifies the published command surface, parser/help behavior, and packaged artifact shape.
+The CLI coordinates the root market repo plus checked-out package repositories:
 
-Install dependencies:
+- `@treeseed/sdk`
+- `@treeseed/ui`
+- `@treeseed/core`
+- `@treeseed/admin`
+- `@treeseed/api`
+- `@treeseed/cli`
+- `@treeseed/agent`
+- `packages/treedx`
 
-```bash
-npm install
-```
+Workflow commands save package repos in dependency order, update submodule pointers, verify package release gates, and avoid one-off provider mutation.
 
-Build the published package output:
+## Save, Stage, And Release
+
+`treeseed save` is the default checkpoint command. It saves dirty package repositories first, restores workspace links, performs lightweight release-candidate validation, and then saves the root market repo.
 
 ```bash
-npm run build
+treeseed save --json "describe the checkpoint"
+treeseed save --verify local --json "describe the checkpoint"
+treeseed save --lane promotion --json "describe the checkpoint"
 ```
 
-Run the package test suite:
+`treeseed stage` and `treeseed release` are promotion-grade commands. Use `--plan` before risky operations:
 
 ```bash
-npm test
+treeseed stage --plan --json "describe the staging change"
+treeseed release --patch --verify-deployed-resources --plan --json
 ```
 
-Run full release verification:
+Interrupted workflow runs are journaled under `.treeseed/workflow`:
 
 ```bash
-npm run release:verify
+treeseed recover --json
+treeseed resume <run-id> --json
 ```
 
-The release verification flow is intentionally stricter than a normal test run:
+## How CLI Fits With Other Packages
 
-1. Build `dist`
-2. Validate publishable output for forbidden workspace references
-3. Assert the published artifact only contains the thin wrapper entrypoints
-4. Run the CLI wrapper test suite
-5. Pack the CLI tarball
-6. Smoke-test the packed install by running `treeseed --help` from the packed artifact
+- `@treeseed/sdk` owns workflow, reconciliation, config, package discovery, and platform primitives.
+- `@treeseed/core` owns the local web runtime used by `treeseed dev`.
+- `@treeseed/admin` and `@treeseed/ui` are consumed by the web app; CLI does not own those routes or components.
+- `@treeseed/api` owns backend API and operations-runner implementation.
+- `@treeseed/agent` owns capacity-provider runtime artifacts that CLI starts or reconciles.
+- TreeDX owns its service/image; CLI exposes package-image workflow commands.
 
-## CI And Publishing
+## Package Development
 
-The GitHub Actions workflows under `.github/workflows/` assume this package is the repository root for the standalone CLI repository.
+From this package root:
 
-- `ci.yml` uses `npm ci`, `npm run build`, `npm test`, and `npm run release:verify`
-- `publish.yml` uses the same verification path before publishing to npm
-- `publish.yml` validates that the pushed tag matches the package version before `npm publish`
-
-Release tags must use this format:
-
-```text
-<version>
+```bash
+npm install
+npm run build
+npm test
+npm run release:verify
 ```
 
-For example, package version `0.1.0` publishes from tag `0.1.0`.
+Release verification checks the packaged command surface, parser/help behavior, build output, and publishable artifact shape.
+
+## What CLI Does Not Own
 
-## Notes
+- SDK reconciliation internals
+- Core web runtime internals
+- Admin routes or UI components
+- backend API implementation
+- capacity-provider runtime implementation
+- TreeDX service internals
+- root market content or ecommerce
 
-- `package-lock.json` should be committed and kept current so `npm ci` remains reproducible in CI and release jobs.
-- The README intentionally documents the command surface at a high level. The canonical source of operation identity and semantics is `@treeseed/sdk`, while `@treeseed/cli` owns argv parsing, help rendering, and terminal formatting.
+See the root [Package Ownership](../../docs/package-ownership.md) guide for cross-package boundaries.

package/dist/cli/handlers/audit.js

@@ -1,4 +1,6 @@
 import {
+  collectTreeseedHostedServiceChecks,
+  collectTreeseedLiveHostedServiceChecks,
   formatTreeseedHostingAuditReport,
   runTreeseedHostingAudit
 } from "@treeseed/sdk/workflow-support";
@@ -45,12 +47,25 @@ const handleAudit = async (invocation, context) => {
       hostKinds: normalizeHostKinds(invocation.args.hostKinds ?? invocation.args.hosts),
       write: context.write
     });
+    const hostedTarget = report.environment === "prod" ? "prod" : report.environment === "local" ? "local" : "staging";
+    const hostedServices = invocation.args.live === true ? await collectTreeseedLiveHostedServiceChecks({
+      tenantRoot: context.cwd,
+      target: hostedTarget,
+      strict: false,
+      env: context.env
+    }) : collectTreeseedHostedServiceChecks({
+      tenantRoot: context.cwd,
+      target: hostedTarget
+    });
     const counts = statusCounts(report.checks);
     if (context.outputFormat === "json") {
       return {
         exitCode: report.ok ? 0 : 1,
         stdout: [],
-        report
+        report: {
+          ...report,
+          hostedServices
+        }
       };
     }
     return guidedResult({
@@ -62,10 +77,20 @@ const handleAudit = async (invocation, context) => {
         { label: "Mode", value: report.repairMode ? "repair" : "read-only" },
         { label: "Passed", value: counts.passed ?? 0 },
         { label: "Warnings", value: (counts.warning ?? 0) + report.warnings.length },
-        { label: "Failed", value: counts.failed ?? 0 }
+        { label: "Failed", value: counts.failed ?? 0 },
+        { label: "Hosted checks", value: `${hostedServices.summary.passed} passed, ${hostedServices.summary.warning} warnings, ${hostedServices.summary.failed} failed, ${hostedServices.summary.skipped} skipped` }
+      ],
+      sections: [
+        {
+          title: "Hosted service checks",
+          lines: hostedServices.checks.map((check) => `${check.provider} ${check.serviceKey ?? check.serviceType} ${check.description}: ${check.status}${check.issues.length ? ` (${check.issues.join("; ")})` : ""}`)
+        }
       ],
       nextSteps: report.nextActions,
-      report,
+      report: {
+        ...report,
+        hostedServices
+      },
       exitCode: report.ok ? 0 : 1
     });
   } catch (error) {

package/dist/cli/handlers/capacity.js

@@ -378,7 +378,7 @@ function runLifecycleAction(action, invocation, context) {
     requireConnection: lifecycleActionRequiresConnection(action),
     overrides: {
       TREESEED_MARKET_URL: market.baseUrl,
-      TREESEED_MARKET_ID: market.id,
+      TREESEED_MANAGER_ID: market.id,
       TREESEED_PROVIDER_HOST_DATA_DIR: resolvedHostDataDir,
       TREESEED_PROVIDER_ENVIRONMENT: providerSelector(invocation),
       ...diagnostic ? { TREESEED_PROVIDER_STARTUP_MODE: "diagnostic" } : {}
@@ -442,7 +442,7 @@ function invokeProviderEntrypoint(action, invocation, context) {
     env: {
       ...context.env,
       TREESEED_MARKET_URL: market.baseUrl,
-      TREESEED_MARKET_ID: market.id,
+      TREESEED_MANAGER_ID: market.id,
       TREESEED_PROVIDER_ENVIRONMENT: providerSelector(invocation)
     },
     encoding: "utf8"

package/dist/cli/handlers/destroy.js

@@ -28,9 +28,11 @@ const handleDestroy = async (invocation, context) => {
       dryRun: invocation.args.dryRun === true,
       force: invocation.args.force === true,
       deleteData: invocation.args.deleteData === true,
+      sweepTreeseed: invocation.args.sweepTreeseed === true,
       removeBuildArtifacts: invocation.args.removeBuildArtifacts === true
     });
     const payload = result.payload;
+    const verification = payload.remoteResult?.verification ?? null;
     return guidedResult({
       command: invocation.commandName || "destroy",
       summary: result.executionMode === "plan" ? "Treeseed destroy plan ready." : "Treeseed destroy completed successfully.",
@@ -38,7 +40,10 @@ const handleDestroy = async (invocation, context) => {
         { label: "Environment", value: payload.scope },
         { label: "Dry run", value: payload.dryRun ? "yes" : "no" },
         { label: "Delete data", value: payload.deleteData ? "yes" : "no" },
-        { label: "Removed build artifacts", value: payload.removeBuildArtifacts ? "yes" : "no" }
+        { label: "Sweep TreeSeed resources", value: payload.sweepTreeseed ? "yes" : "no" },
+        { label: "Removed build artifacts", value: payload.removeBuildArtifacts ? "yes" : "no" },
+        ...verification?.cloudflare ? [{ label: "Cloudflare remaining", value: String(verification.cloudflare.totalRemaining ?? 0) }] : [],
+        ...verification?.localDocker ? [{ label: "Local Docker remaining", value: String(verification.localDocker.totalRemaining ?? 0) }] : []
       ],
       nextSteps: renderWorkflowNextSteps(result),
       report: result

package/dist/cli/handlers/dev.js

@@ -2,6 +2,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import { dirname, resolve } from "node:path";
 import { ensureLocalWorkspaceLinks, findNearestTreeseedWorkspaceRoot, resolveTreeseedLaunchEnvironment } from "@treeseed/sdk/workflow-support";
+import { discoverTreeseedApplications } from "@treeseed/sdk/hosting";
 import { workflowErrorResult } from "./workflow.js";
 import { fail } from "./utils.js";
 const require2 = createRequire(import.meta.url);
@@ -52,12 +53,17 @@ const handleDev = async (invocation, context) => {
     }
     const feedback = typeof invocation.args.feedback === "string" ? invocation.args.feedback : void 0;
     const watch = feedback !== "off";
+    const appId = typeof invocation.args.app === "string" && invocation.args.app.trim() ? invocation.args.app.trim() : void 0;
+    const apiMode = typeof invocation.args.api === "string" && invocation.args.api.trim() ? invocation.args.api.trim() : "auto";
     const subcommand = typeof invocation.positionals[0] === "string" ? invocation.positionals[0] : "";
     const managedSubcommands = /* @__PURE__ */ new Set(["start", "status", "logs", "stop", "restart"]);
     if (subcommand && !managedSubcommands.has(subcommand)) {
       return fail(`Unknown dev subcommand "${subcommand}". Use start, status, logs, stop, or restart.`);
     }
-    const passthroughArgs = ["--surfaces", "web,api"];
+    const discoveredApps = discoverTreeseedApplications(context.cwd);
+    const hasApiApp = discoveredApps.some((app) => app.id === "api");
+    const selectedSurfaces = appId === "api" ? "api" : appId === "web" || apiMode === "remote" ? "web" : hasApiApp ? "web,api" : "web";
+    const passthroughArgs = ["--surfaces", selectedSurfaces];
     const forwardStringOption = (name, flag) => {
       const value = invocation.args[name];
       if (typeof value === "string" && value.trim().length > 0) {
@@ -117,7 +123,15 @@ const handleDev = async (invocation, context) => {
         watch,
         executable: resolved.command,
         args,
-        workspaceLinks
+        workspaceLinks,
+        appId: appId ?? null,
+        apiMode,
+        discoveredApps: discoveredApps.map((app) => ({
+          id: app.id,
+          relativeRoot: app.relativeRoot,
+          roles: app.roles
+        })),
+        selectedSurfaces
       }
     };
   } catch (error) {

package/dist/cli/handlers/doctor.js

@@ -1,6 +1,6 @@
 import { existsSync } from "node:fs";
 import { resolve } from "node:path";
-import { collectCliPreflight } from "@treeseed/sdk/workflow-support";
+import { collectCliPreflight, collectTreeseedDeploymentReadiness, collectTreeseedHostedServiceChecks } from "@treeseed/sdk/workflow-support";
 import { guidedResult } from "./utils.js";
 import { applyTreeseedSafeRepairs } from "../repair.js";
 import { createWorkflowSdk, workflowErrorResult } from "./workflow.js";
@@ -8,6 +8,12 @@ const handleDoctor = async (invocation, context) => {
   try {
     const status = await createWorkflowSdk(context).status();
     const state = status.payload;
+    const hostedServices = invocation.args.live === true || invocation.args.hostedServices === true ? collectTreeseedHostedServiceChecks({
+      tenantRoot: context.cwd,
+      target: state.branchRole === "production" || state.branchName === "main" ? "prod" : state.branchRole === "staging" || state.branchName === "staging" ? "staging" : "local"
+    }) : null;
+    const hostedTarget = state.branchRole === "production" || state.branchName === "main" ? "prod" : state.branchRole === "staging" || state.branchName === "staging" ? "staging" : "local";
+    const deploymentReadiness = invocation.args.live === true || invocation.args.hostedServices === true ? collectTreeseedDeploymentReadiness({ tenantRoot: context.cwd, environment: hostedTarget }) : null;
     const performedFixes = invocation.args.fix === true && state.deployConfigPresent ? applyTreeseedSafeRepairs(state.cwd) : [];
     const preflight = collectCliPreflight({ cwd: context.cwd, requireAuth: false });
     const railwayManagedServicesEnabled = Object.values(state.managedServices).some((service) => service.enabled);
@@ -65,7 +71,9 @@ const handleDoctor = async (invocation, context) => {
         { label: "Optional follow-up", value: optional.length },
         { label: "Safe fixes applied", value: performedFixes.length },
         { label: "Branch", value: state.branchName ?? "(none)" },
-        { label: "Workspace root", value: state.workspaceRoot ? "yes" : "no" }
+        { label: "Workspace root", value: state.workspaceRoot ? "yes" : "no" },
+        ...hostedServices ? [{ label: "Hosted checks", value: `${hostedServices.summary.passed} passed, ${hostedServices.summary.warning} warnings, ${hostedServices.summary.failed} failed, ${hostedServices.summary.skipped} skipped` }] : [],
+        ...deploymentReadiness ? [{ label: "Deployment readiness", value: `${deploymentReadiness.summary.passed} passed, ${deploymentReadiness.summary.failed} failed` }] : []
       ],
       nextSteps: [
         ...mustFixNow.map((item) => item),
@@ -77,7 +85,9 @@ const handleDoctor = async (invocation, context) => {
         preflight,
         performedFixes,
         mustFixNow,
-        optional
+        optional,
+        hostedServices,
+        deploymentReadiness
       },
       exitCode: mustFixNow.length === 0 ? 0 : 1
     });

package/dist/cli/handlers/hosting.d.ts

@@ -0,0 +1,2 @@
+import type { TreeseedCommandHandler } from '../types.js';
+export declare const handleHosting: TreeseedCommandHandler;