@treeseed/cli 0.6.34 → 0.6.36

package/dist/cli/handlers/tags-cleanup.d.ts

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

package/dist/cli/handlers/tags-cleanup.js

@@ -0,0 +1,42 @@
+import { guidedResult } from "./utils.js";
+import { createWorkflowSdk, renderWorkflowNextSteps, workflowErrorResult } from "./workflow.js";
+function parseIncludePackages(value) {
+  if (typeof value !== "string" || value.trim().length === 0) return void 0;
+  return value.split(",").map((entry) => entry.trim()).filter(Boolean);
+}
+const handleTagsCleanup = async (invocation, context) => {
+  try {
+    const result = await createWorkflowSdk(context).tagsCleanup({
+      includePackages: parseIncludePackages(invocation.args.includePackages),
+      branchScope: typeof invocation.args.branchScope === "string" ? invocation.args.branchScope : void 0,
+      plan: invocation.args.plan === true || invocation.args.dryRun === true,
+      dryRun: invocation.args.dryRun === true
+    });
+    const payload = result.payload;
+    return guidedResult({
+      command: invocation.commandName || "tags:cleanup",
+      summary: result.executionMode === "plan" ? "Treeseed dev tag cleanup plan ready." : "Treeseed dev tag cleanup completed.",
+      facts: [
+        { label: "Status", value: payload.status ?? (result.executionMode === "plan" ? "planned" : "completed") },
+        { label: "Branch scope", value: payload.branchScope ?? "all" },
+        { label: "Included packages", value: (payload.includePackages ?? []).join(", ") || "all" },
+        { label: "Candidate tags", value: String(payload.candidateCount ?? 0) },
+        { label: "Cleaned tags", value: String(payload.cleanedCount ?? 0) },
+        { label: "Skipped tags", value: String(payload.skippedCount ?? 0) }
+      ],
+      sections: [
+        {
+          title: "Repositories",
+          lines: (payload.repos ?? []).map((repo) => `- ${repo.name ?? "repo"}: candidates ${repo.candidateCount ?? 0}, cleaned ${repo.cleanedCount ?? 0}, skipped ${repo.skippedCount ?? 0}`)
+        }
+      ],
+      nextSteps: renderWorkflowNextSteps(result),
+      report: result
+    });
+  } catch (error) {
+    return workflowErrorResult(error);
+  }
+};
+export {
+  handleTagsCleanup
+};

package/dist/cli/handlers/tool-wrapper.d.ts

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

package/dist/cli/handlers/tool-wrapper.js

@@ -0,0 +1,77 @@
+import {
+  createTreeseedManagedToolEnv,
+  resolveTreeseedLaunchEnvironment,
+  resolveTreeseedToolCommand
+} from "@treeseed/sdk/workflow-support";
+import { workflowErrorResult } from "./workflow.js";
+const WRAPPED_TOOLS = /* @__PURE__ */ new Set(["gh", "railway", "wrangler"]);
+const ENVIRONMENT_SCOPES = /* @__PURE__ */ new Set(["local", "staging", "prod"]);
+function wrappedToolName(value) {
+  if (WRAPPED_TOOLS.has(value)) {
+    return value;
+  }
+  throw new Error(`Unsupported Treeseed tool wrapper: ${value}`);
+}
+function wrapperScope(value) {
+  if (typeof value === "string" && ENVIRONMENT_SCOPES.has(value)) {
+    return value;
+  }
+  return "staging";
+}
+const handleToolWrapper = (invocation, context) => {
+  try {
+    const toolName = wrappedToolName(invocation.commandName);
+    const scope = wrapperScope(invocation.args.environment);
+    const launchEnv = resolveTreeseedLaunchEnvironment({
+      tenantRoot: context.cwd,
+      scope,
+      baseEnv: { ...process.env, ...context.env ?? {} }
+    });
+    const managedEnv = createTreeseedManagedToolEnv({
+      ...process.env,
+      ...context.env ?? {},
+      ...launchEnv,
+      TREESEED_ACTIVE_ENVIRONMENT: scope
+    });
+    const resolved = resolveTreeseedToolCommand(toolName, { env: managedEnv });
+    if (!resolved) {
+      return {
+        exitCode: 1,
+        stderr: [
+          `Treeseed managed tool \`${toolName}\` is not installed or could not be resolved.`,
+          "Run `npx trsd install --json` and retry the wrapper command."
+        ],
+        report: {
+          command: toolName,
+          ok: false,
+          scope,
+          error: `Unable to resolve ${toolName}.`
+        }
+      };
+    }
+    const targetArgs = invocation.positionals;
+    const result = context.spawn(resolved.command, [...resolved.argsPrefix, ...targetArgs], {
+      cwd: context.cwd,
+      env: managedEnv,
+      stdio: "inherit"
+    });
+    return {
+      exitCode: result.status ?? 1,
+      suppressJsonResult: true,
+      report: {
+        command: toolName,
+        ok: (result.status ?? 1) === 0,
+        scope,
+        executable: resolved.command,
+        binaryPath: resolved.binaryPath,
+        argsPrefix: resolved.argsPrefix,
+        args: targetArgs
+      }
+    };
+  } catch (error) {
+    return workflowErrorResult(error);
+  }
+};
+export {
+  handleToolWrapper
+};

package/dist/cli/operations-registry.js

@@ -114,7 +114,7 @@ function genericWarnings(spec) {
   if (spec.name === "release") {
     warnings.push("Release operations assume staging is the source of truth for what should move to production. Treat version bumps and promotion as deliberate release events.");
   }
-  if (spec.executionMode === "passthrough") {
+  if (spec.group === "Passthrough") {
     warnings.push("This command forwards to another CLI surface. Flags after `--` or positional forwarding may follow the target tool semantics rather than Treeseed-specific semantics.");
   }
   return warnings;
@@ -148,6 +148,9 @@ function mergeHelpSpec(metadata, overlay, spec) {
   };
 }
 const PASS_THROUGH_ARGS = (invocation) => ({ args: invocation.rawArgs });
+const TOOL_WRAPPER_OPTIONS = [
+  { name: "environment", flags: "--environment <scope>", description: "Treeseed environment scope used to decrypt and inject provider credentials.", kind: "enum", values: ["local", "staging", "prod"] }
+];
 const CLI_COMMAND_OVERLAYS = /* @__PURE__ */ new Map([
   ["status", command({
     options: [
@@ -456,6 +459,43 @@ const CLI_COMMAND_OVERLAYS = /* @__PURE__ */ new Map([
     executionMode: "handler",
     handlerName: "stage"
   })],
+  ["tags:cleanup", command({
+    usage: "treeseed tags:cleanup [--plan|--dry-run] [--include-packages <names>] [--branch-scope <staging|preview|all>] [--json]",
+    options: [
+      { name: "plan", flags: "--plan", description: "Compute stale dev tag cleanup without deleting tags.", kind: "boolean" },
+      { name: "dryRun", flags: "--dry-run", description: "Alias for --plan.", kind: "boolean" },
+      { name: "includePackages", flags: "--include-packages <names>", description: "Comma-separated package names to inspect.", kind: "string" },
+      { name: "branchScope", flags: "--branch-scope <scope>", description: "Limit cleanup to staging tags, preview tags, or all dev branch tags.", kind: "enum", values: ["staging", "preview", "all"] },
+      { name: "json", flags: "--json", description: "Emit machine-readable JSON instead of human-readable text.", kind: "boolean" }
+    ],
+    examples: ["treeseed tags:cleanup --plan", "treeseed tags:cleanup --branch-scope staging", "treeseed tags:cleanup --include-packages @treeseed/sdk,@treeseed/core --json"],
+    notes: ["Only deletes Treeseed-managed package dev tags older than each package current version line."],
+    help: {
+      workflowPosition: "maintain workspace",
+      longSummary: [
+        "Tags cleanup removes stale Treeseed-managed package dev tags from staging and preview branch saves."
+      ],
+      whenToUse: [
+        "Use this when old staging or preview package tags have accumulated after many saves and releases.",
+        "Use `--plan` first to inspect exactly which tags would be removed."
+      ],
+      outcomes: [
+        "Plans or deletes stale local and origin package dev tags.",
+        "Preserves current-version dev tags, active dependency references, stable release tags, and non-Treeseed tags."
+      ],
+      examples: [
+        example("treeseed tags:cleanup --plan", "Inspect cleanup", "Show stale tag candidates without deleting anything."),
+        example("treeseed tags:cleanup --branch-scope preview", "Clean preview tags", "Delete stale non-staging branch dev tags while leaving staging dev tags alone."),
+        example("treeseed tags:cleanup --json", "Automate cleanup", "Emit structured per-repository cleanup counts and skipped reasons.")
+      ],
+      relatedDetails: [
+        related("release", "Release also runs safe dev tag cleanup after successful stable promotion."),
+        related("status", "Use `status` to inspect workspace alignment before maintenance.")
+      ]
+    },
+    executionMode: "handler",
+    handlerName: "tags:cleanup"
+  })],
   ["resume", command({
     arguments: [{ name: "run-id", description: "Interrupted workflow run id to resume.", required: true }],
     options: [{ name: "json", flags: "--json", description: "Emit machine-readable JSON instead of human-readable text.", kind: "boolean" }],
@@ -1217,6 +1257,78 @@ const CLI_COMMAND_OVERLAYS = /* @__PURE__ */ new Map([
   ["starlight:patch", command({ examples: ["treeseed starlight:patch"], executionMode: "adapter" })]
 ]);
 const CLI_ONLY_OPERATION_SPECS = [
+  {
+    id: "tools.gh",
+    name: "gh",
+    aliases: [],
+    group: "Passthrough",
+    summary: "Run the managed GitHub CLI with Treeseed environment credentials.",
+    description: "Decrypt Treeseed machine configuration for the selected environment and pass it to the managed GitHub CLI.",
+    provider: "default",
+    related: ["tools", "install", "config"],
+    usage: "treeseed gh [--environment staging] -- <gh-args>",
+    arguments: [{ name: "args", description: "Arguments forwarded to GitHub CLI.", required: false }],
+    options: TOOL_WRAPPER_OPTIONS,
+    examples: ["treeseed gh --environment staging -- run list --limit 5", "treeseed gh -- repo view"],
+    help: {
+      longSummary: ["The GitHub wrapper resolves the Treeseed-managed `gh` executable, decrypts scoped machine configuration, and passes the resulting GitHub token only to the child process environment."],
+      whenToUse: ["Use this when provider auth lives in Treeseed machine config rather than your shell environment."],
+      beforeYouRun: ["Run from a Treeseed project. Use `--environment staging` unless you intentionally need local or production credentials."],
+      automationNotes: ["Use `--` before target CLI flags when a flag could be parsed by Treeseed itself. The wrapper does not print decrypted secrets."]
+    },
+    helpVisible: true,
+    helpFeatured: false,
+    executionMode: "handler",
+    handlerName: "gh"
+  },
+  {
+    id: "tools.railway",
+    name: "railway",
+    aliases: [],
+    group: "Passthrough",
+    summary: "Run the managed Railway CLI with Treeseed environment credentials.",
+    description: "Decrypt Treeseed machine configuration for the selected environment and pass it to the managed Railway CLI.",
+    provider: "default",
+    related: ["tools", "install", "config"],
+    usage: "treeseed railway [--environment staging] -- <railway-args>",
+    arguments: [{ name: "args", description: "Arguments forwarded to Railway CLI.", required: false }],
+    options: TOOL_WRAPPER_OPTIONS,
+    examples: ["treeseed railway --environment staging -- whoami", "treeseed railway --environment staging -- status"],
+    help: {
+      longSummary: ["The Railway wrapper resolves the Treeseed-managed Railway executable, decrypts scoped machine configuration, and passes the resulting Railway token only to the child process environment."],
+      whenToUse: ["Use this to debug Railway projects and service builds with the same decrypted `RAILWAY_API_TOKEN` Treeseed deploys use."],
+      beforeYouRun: ["Run from a Treeseed project. Use `--environment staging` when inspecting staging deployments."],
+      automationNotes: ["Use `--` before target CLI flags when a flag could be parsed by Treeseed itself. The wrapper does not print decrypted secrets."]
+    },
+    helpVisible: true,
+    helpFeatured: false,
+    executionMode: "handler",
+    handlerName: "railway"
+  },
+  {
+    id: "tools.wrangler",
+    name: "wrangler",
+    aliases: [],
+    group: "Passthrough",
+    summary: "Run the managed Wrangler CLI with Treeseed environment credentials.",
+    description: "Decrypt Treeseed machine configuration for the selected environment and pass it to the managed Wrangler CLI.",
+    provider: "default",
+    related: ["tools", "install", "config"],
+    usage: "treeseed wrangler [--environment staging] -- <wrangler-args>",
+    arguments: [{ name: "args", description: "Arguments forwarded to Wrangler CLI.", required: false }],
+    options: TOOL_WRAPPER_OPTIONS,
+    examples: ["treeseed wrangler --environment staging -- whoami", "treeseed wrangler --environment staging -- d1 list"],
+    help: {
+      longSummary: ["The Wrangler wrapper resolves the Treeseed-managed Wrangler executable, decrypts scoped machine configuration, and passes the resulting Cloudflare token and account settings only to the child process environment."],
+      whenToUse: ["Use this to debug Cloudflare resources with the same decrypted `CLOUDFLARE_API_TOKEN` and account settings Treeseed deploys use."],
+      beforeYouRun: ["Run from a Treeseed project. Use `--environment staging` when inspecting staging resources."],
+      automationNotes: ["Use `--` before target CLI flags when a flag could be parsed by Treeseed itself. The wrapper does not print decrypted secrets."]
+    },
+    helpVisible: true,
+    helpFeatured: false,
+    executionMode: "handler",
+    handlerName: "wrangler"
+  },
   {
     id: "market.registry",
     name: "market",

package/dist/cli/parser.js

@@ -21,6 +21,10 @@ function parseTreeseedInvocation(command, argv) {
       const [flag, inlineValue] = current.split("=", 2);
       const spec = byFlag.get(flag);
       if (!spec) {
+        if (command.group === "Passthrough") {
+          positionals.push(current);
+          continue;
+        }
         throw new Error(`Unknown option: ${flag}`);
       }
       if (spec.kind === "boolean") {

package/dist/cli/registry.d.ts

@@ -18,6 +18,7 @@ export declare const COMMAND_HANDLERS: {
     readonly tasks: import("./operations-types.js").TreeseedCommandHandler;
     readonly switch: import("./operations-types.js").TreeseedCommandHandler;
     readonly stage: import("./operations-types.js").TreeseedCommandHandler;
+    readonly 'tags:cleanup': import("./operations-types.js").TreeseedCommandHandler;
     readonly resume: import("./operations-types.js").TreeseedCommandHandler;
     readonly recover: import("./operations-types.js").TreeseedCommandHandler;
     readonly export: import("./operations-types.js").TreeseedCommandHandler;
@@ -28,6 +29,9 @@ export declare const COMMAND_HANDLERS: {
     readonly teams: import("./operations-types.js").TreeseedCommandHandler;
     readonly projects: import("./operations-types.js").TreeseedCommandHandler;
     readonly packs: import("./operations-types.js").TreeseedCommandHandler;
+    readonly gh: import("./operations-types.js").TreeseedCommandHandler;
+    readonly railway: import("./operations-types.js").TreeseedCommandHandler;
+    readonly wrangler: import("./operations-types.js").TreeseedCommandHandler;
     readonly 'secrets:status': import("./operations-types.js").TreeseedCommandHandler;
     readonly 'secrets:unlock': import("./operations-types.js").TreeseedCommandHandler;
     readonly 'secrets:lock': import("./operations-types.js").TreeseedCommandHandler;

package/dist/cli/registry.js

@@ -23,6 +23,7 @@ import { handleMarket } from "./handlers/market.js";
 import { handleTeams } from "./handlers/teams.js";
 import { handleProjects } from "./handlers/projects.js";
 import { handlePacks } from "./handlers/packs.js";
+import { handleToolWrapper } from "./handlers/tool-wrapper.js";
 import {
   handleSecretsLock,
   handleSecretsMigrateKey,
@@ -34,6 +35,7 @@ import {
 import { handleTasks } from "./handlers/tasks.js";
 import { handleSwitch } from "./handlers/switch.js";
 import { handleStage } from "./handlers/stage.js";
+import { handleTagsCleanup } from "./handlers/tags-cleanup.js";
 import { handleExport } from "./handlers/export.js";
 import { handleResume } from "./handlers/resume.js";
 import { handleRecover } from "./handlers/recover.js";
@@ -57,6 +59,7 @@ const COMMAND_HANDLERS = {
   tasks: handleTasks,
   switch: handleSwitch,
   stage: handleStage,
+  "tags:cleanup": handleTagsCleanup,
   resume: handleResume,
   recover: handleRecover,
   [workspaceCommand("status")]: handleWorkspace,
@@ -70,6 +73,9 @@ const COMMAND_HANDLERS = {
   teams: handleTeams,
   projects: handleProjects,
   packs: handlePacks,
+  gh: handleToolWrapper,
+  railway: handleToolWrapper,
+  wrangler: handleToolWrapper,
   "secrets:status": handleSecretsStatus,
   "secrets:unlock": handleSecretsUnlock,
   "secrets:lock": handleSecretsLock,

package/dist/cli/runtime.js

@@ -14,6 +14,14 @@ const require2 = createRequire(import.meta.url);
 function isHelpFlag(value) {
   return value === "--help" || value === "-h";
 }
+function shouldRenderCommandHelp(spec, argv) {
+  if (spec.group !== "Passthrough") {
+    return argv.some(isHelpFlag);
+  }
+  const separatorIndex = argv.indexOf("--");
+  const treeseedArgs = separatorIndex >= 0 ? argv.slice(0, separatorIndex) : argv;
+  return treeseedArgs.some(isHelpFlag);
+}
 function isNoColorFlag(value) {
   return value === "--no-color";
 }
@@ -294,7 +302,7 @@ class TreeseedOperationsSdk {
       lines.push("Run `treeseed help` to see the full command list.");
       return writeTreeseedResult({ exitCode: 1, stderr: [lines.join("\n")] }, context);
     }
-    if (argv.some(isHelpFlag)) {
+    if (shouldRenderCommandHelp(spec, argv)) {
       if (shouldUseInkHelp(context)) {
         const helpExitCode = await renderTreeseedHelpInk(spec.name, context);
         if (typeof helpExitCode === "number") {
@@ -376,7 +384,7 @@ async function executeTreeseedCommand(commandName, argv, context) {
   if (!spec) {
     return cliOperationsSdk.executeOperation({ commandName, argv: cleanArgv }, commandContext);
   }
-  if (cleanArgv.some(isHelpFlag)) {
+  if (shouldRenderCommandHelp(spec, cleanArgv)) {
     return cliOperationsSdk.executeOperation({ commandName, argv: cleanArgv }, commandContext);
   }
   const resolved = resolveTreeseedCommandCwd(spec, commandContext.cwd);
@@ -402,7 +410,7 @@ async function runTreeseedCli(argv, overrides = {}) {
   if (!spec) {
     return cliOperationsSdk.run(cleanArgv, { ...overrides, colorEnabled });
   }
-  if (cleanArgv.slice(1).some(isHelpFlag)) {
+  if (shouldRenderCommandHelp(spec, cleanArgv.slice(1))) {
     return cliOperationsSdk.run(cleanArgv, { ...overrides, colorEnabled });
   }
   const baseCwd = overrides.cwd ?? process.cwd();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@treeseed/cli",
-  "version": "0.6.34",
+  "version": "0.6.36",
   "description": "Operator-facing Treeseed CLI package.",
   "license": "AGPL-3.0-only",
   "repository": {
@@ -45,7 +45,7 @@
     "release:publish": "node ./scripts/run-ts.mjs ./scripts/publish-package.ts"
   },
   "dependencies": {
-    "@treeseed/sdk": "0.6.38",
+    "@treeseed/sdk": "0.6.40",
     "ink": "^7.0.0",
     "react": "^19.2.5"
   },