@treeseed/cli 0.4.6 → 0.4.8

package/README.md

@@ -14,10 +14,18 @@ This package publishes the `treeseed` binary. `@treeseed/sdk` owns the reusable
 Install the CLI with its runtime dependencies:
 
 ```bash
-npm install @treeseed/cli @treeseed/core @treeseed/sdk @treeseed/agent
+npm install @treeseed/cli @treeseed/core @treeseed/sdk
 ```
 
-`@treeseed/cli` is a thin installable wrapper over `@treeseed/sdk` workflow and operations interfaces plus the `@treeseed/agent` command namespace. `treeseed dev` resolves and delegates to the tenant-installed `@treeseed/core` runtime. In normal consumer installs, npm resolves the runtime dependencies automatically.
+`@treeseed/cli` is a thin installable wrapper over `@treeseed/sdk` workflow and operations interfaces plus the `@treeseed/core` runtime namespaces. `treeseed dev` and `treeseed agents ...` resolve and delegate to the tenant-installed or sibling-workspace `@treeseed/core` runtime. In normal consumer installs, npm resolves the runtime dependencies automatically.
+
+Workflow guarantees:
+
+- `treeseed init`, `treeseed config`, and `treeseed release` resolve the project from nested directories and do not rely on the currently checked-out task branch.
+- `treeseed switch` requires a clean worktree before leaving the current branch and creates new task branches from the latest `staging`.
+- `treeseed save` is the canonical checkpoint command: it syncs the current branch with origin, succeeds even when no new changes exist, and can create or refresh preview deployments with `--preview`.
+- `treeseed stage` and `treeseed close` auto-save meaningful uncommitted task-branch changes before merge or cleanup, then leave the repository on `staging`.
+- `treeseed release` completes on `staging` after promoting `staging` into `main` and pushing the release tag.
 
 After installation, the published binary is available as:
 
@@ -34,7 +42,7 @@ The main workflow commands exposed by the current CLI are:
 - `treeseed tasks [--json]`
 - `treeseed switch <branch-name> [--preview]`
 - `treeseed dev`
-- `treeseed save "<commit message>"`
+- `treeseed save [--preview] "<commit message>"`
 - `treeseed stage "<resolution message>"`
 - `treeseed close "<close reason>"`
 - `treeseed release --major|--minor|--patch`
@@ -51,7 +59,7 @@ treeseed status
 treeseed config
 treeseed switch feature/search-improvements --preview
 treeseed dev
-treeseed save "feat: add search filters"
+treeseed save --preview "feat: add search filters"
 treeseed stage "feat: add search filters"
 treeseed release --patch
 treeseed status --json

package/dist/cli/handlers/close.js

@@ -11,8 +11,10 @@ const handleClose = async (invocation, context) => {
       summary: "Treeseed close completed successfully.",
       facts: [
         { label: "Closed branch", value: payload.branchName },
+        { label: "Auto-saved", value: payload.autoSaved ? "yes" : "no" },
         { label: "Deprecated tag", value: payload.deprecatedTag.tagName },
-        { label: "Preview cleanup", value: payload.previewCleanup.performed ? "performed" : "not needed" }
+        { label: "Preview cleanup", value: payload.previewCleanup.performed ? "performed" : "not needed" },
+        { label: "Final branch", value: payload.finalBranch }
       ],
       nextSteps: renderWorkflowNextSteps(result),
       report: payload

package/dist/cli/handlers/release.js

@@ -14,7 +14,9 @@ const handleRelease = async (invocation, context) => {
         { label: "Release level", value: payload.level },
         { label: "Root version", value: payload.rootVersion },
         { label: "Release tag", value: payload.releaseTag },
-        { label: "Updated packages", value: payload.touchedPackages.length }
+        { label: "Released commit", value: payload.releasedCommit.slice(0, 12) },
+        { label: "Updated packages", value: payload.touchedPackages.length },
+        { label: "Final branch", value: payload.finalBranch }
       ],
       nextSteps: renderWorkflowNextSteps(result),
       report: payload

package/dist/cli/handlers/save.js

@@ -4,18 +4,20 @@ const handleSave = async (invocation, context) => {
   try {
     const result = await createWorkflowSdk(context).save({
       message: invocation.positionals.join(" ").trim(),
-      hotfix: invocation.args.hotfix === true
+      hotfix: invocation.args.hotfix === true,
+      preview: invocation.args.preview === true
     });
     const payload = result.payload;
     return guidedResult({
       command: invocation.commandName || "save",
-      summary: "Treeseed save completed successfully.",
+      summary: payload.noChanges ? "Treeseed save found no new changes and confirmed branch sync." : "Treeseed save completed successfully.",
       facts: [
         { label: "Branch", value: payload.branch },
         { label: "Environment scope", value: payload.scope },
         { label: "Hotfix", value: payload.hotfix ? "yes" : "no" },
         { label: "Commit", value: payload.commitSha.slice(0, 12) },
-        { label: "Preview refreshed", value: payload.previewRefresh ? "yes" : "no" }
+        { label: "Commit created", value: payload.commitCreated ? "yes" : "no" },
+        { label: "Preview action", value: payload.previewAction?.status ?? "skipped" }
       ],
       nextSteps: renderWorkflowNextSteps(result),
       report: payload

package/dist/cli/handlers/stage.js

@@ -12,9 +12,11 @@ const handleStage = async (invocation, context) => {
       facts: [
         { label: "Merged branch", value: payload.branchName },
         { label: "Merge target", value: payload.mergeTarget },
+        { label: "Auto-saved", value: payload.autoSaved ? "yes" : "no" },
         { label: "Deprecated tag", value: payload.deprecatedTag.tagName },
         { label: "Staging wait", value: payload.stagingWait.status },
-        { label: "Preview cleanup", value: payload.previewCleanup.performed ? "performed" : "not needed" }
+        { label: "Preview cleanup", value: payload.previewCleanup.performed ? "performed" : "not needed" },
+        { label: "Final branch", value: payload.finalBranch }
       ],
       nextSteps: renderWorkflowNextSteps(result),
       report: payload

package/dist/cli/help.js

@@ -108,7 +108,7 @@ function renderTreeseedHelp(commandName) {
       "  treeseed agents --help",
       "",
       "Notes",
-      "  - Delegates to the `@treeseed/agent` CLI contract.",
+      "  - Delegates to the integrated `@treeseed/core` agent runtime.",
       "  - Use `treeseed agents --help` to list supported agent subcommands."
     ].join("\n");
   }

package/dist/cli/operations-registry.js

@@ -34,13 +34,14 @@ const CLI_COMMAND_OVERLAYS = /* @__PURE__ */ new Map([
     handlerName: "switch"
   })],
   ["save", command({
-    usage: "treeseed save [--hotfix] <message> [--json]",
+    usage: "treeseed save [--hotfix] [--preview] <message> [--json]",
     arguments: [{ name: "message", description: "Git commit message for the save operation.", required: true, kind: "message_tail" }],
     options: [
       { name: "hotfix", flags: "--hotfix", description: "Allow save on main for an explicit hotfix.", kind: "boolean" },
+      { name: "preview", flags: "--preview", description: "Create or refresh the branch preview during save.", kind: "boolean" },
       { name: "json", flags: "--json", description: "Emit machine-readable JSON instead of human-readable text.", kind: "boolean" }
     ],
-    examples: ['treeseed save "feat: add search filters"', 'treeseed save --hotfix "fix: unblock production form submit"'],
+    examples: ['treeseed save "feat: add search filters"', 'treeseed save --preview "feat: add search filters"', 'treeseed save --hotfix "fix: unblock production form submit"'],
     executionMode: "handler",
     handlerName: "save"
   })],
@@ -49,6 +50,7 @@ const CLI_COMMAND_OVERLAYS = /* @__PURE__ */ new Map([
     arguments: [{ name: "message", description: "Reason for closing the task without staging it.", required: true, kind: "message_tail" }],
     options: [{ name: "json", flags: "--json", description: "Emit machine-readable JSON instead of human-readable text.", kind: "boolean" }],
     examples: ['treeseed close "superseded by feature/search-v2"'],
+    notes: ["Auto-saves meaningful uncommitted task-branch changes before cleanup unless disabled in the workflow API."],
     executionMode: "handler",
     handlerName: "close"
   })],
@@ -57,6 +59,7 @@ const CLI_COMMAND_OVERLAYS = /* @__PURE__ */ new Map([
     arguments: [{ name: "message", description: "Resolution message for the staged task.", required: true, kind: "message_tail" }],
     options: [{ name: "json", flags: "--json", description: "Emit machine-readable JSON instead of human-readable text.", kind: "boolean" }],
     examples: ['treeseed stage "feat: add search filters"'],
+    notes: ["Auto-saves meaningful uncommitted task-branch changes before merging into staging."],
     executionMode: "handler",
     handlerName: "stage"
   })],

package/dist/cli/runtime.d.ts

@@ -19,13 +19,13 @@ export declare class TreeseedOperationsSdk {
     private executeHandler;
     private executeAdapter;
     private executeAgents;
-    executeOperation(request: TreeseedOperationRequest, overrides?: Partial<TreeseedCommandContext>): Promise<number>;
-    run(argv: string[], overrides?: Partial<TreeseedCommandContext>): Promise<number>;
+    executeOperation(request: TreeseedOperationRequest, overrides?: Partial<TreeseedCommandContext>): Promise<any>;
+    run(argv: string[], overrides?: Partial<TreeseedCommandContext>): Promise<any>;
 }
 export declare function resolveTreeseedCommandCwd(spec: TreeseedOperationSpec, cwd: string): {
     cwd: string;
     resolvedProjectRoot: string | null;
     resolvedWorkspaceRoot: any;
 };
-export declare function executeTreeseedCommand(commandName: string, argv: string[], context: TreeseedCommandContext): Promise<number>;
-export declare function runTreeseedCli(argv: string[], overrides?: Partial<TreeseedCommandContext>): Promise<number>;
+export declare function executeTreeseedCommand(commandName: string, argv: string[], context: TreeseedCommandContext): Promise<any>;
+export declare function runTreeseedCli(argv: string[], overrides?: Partial<TreeseedCommandContext>): Promise<any>;

package/dist/cli/runtime.js

@@ -1,10 +1,15 @@
+import { existsSync, readFileSync } from "node:fs";
 import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+import { dirname, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
 import { findNearestTreeseedRoot, findNearestTreeseedWorkspaceRoot } from "@treeseed/sdk/workflow-support";
 import { TreeseedOperationsSdk as SdkOperationsRuntime } from "@treeseed/sdk/operations";
 import { COMMAND_HANDLERS } from "./registry.js";
 import { renderTreeseedHelp, renderUsage, suggestTreeseedCommands } from "./operations-help.js";
 import { parseTreeseedInvocation, validateTreeseedInvocation } from "./operations-parser.js";
 import { findTreeseedOperation, TRESEED_OPERATION_SPECS } from "./operations-registry.js";
+const require2 = createRequire(import.meta.url);
 function isHelpFlag(value) {
   return value === "--help" || value === "-h";
 }
@@ -16,6 +21,43 @@ function defaultWrite(output, stream = "stdout") {
 function defaultSpawn(command, args, options) {
   return spawnSync(command, args, options);
 }
+function resolveCoreAgentCliEntrypoint(cwd) {
+  const workspaceRoot = findNearestTreeseedWorkspaceRoot(cwd) ?? cwd;
+  const workspacePackageJsonPath = resolve(workspaceRoot, "packages", "core", "package.json");
+  const siblingPackageJsonPath = resolve(cwd, "..", "core", "package.json");
+  const installedPackageJsonPath = resolve(cwd, "node_modules", "@treeseed", "core", "package.json");
+  let packageJsonPath = workspacePackageJsonPath;
+  if (!existsSync(packageJsonPath)) {
+    packageJsonPath = existsSync(siblingPackageJsonPath) ? siblingPackageJsonPath : installedPackageJsonPath;
+  }
+  if (!existsSync(packageJsonPath)) {
+    try {
+      const resolvedPath = require2.resolve("@treeseed/core", { paths: [cwd] });
+      let currentDir = dirname(resolvedPath);
+      while (!existsSync(resolve(currentDir, "package.json"))) {
+        const parentDir = dirname(currentDir);
+        if (parentDir === currentDir) {
+          throw new Error("Unable to resolve the installed @treeseed/core package root.");
+        }
+        currentDir = parentDir;
+      }
+      packageJsonPath = resolve(currentDir, "package.json");
+    } catch {
+      throw new Error(
+        "Treeseed agent commands require the integrated `@treeseed/core` runtime. Install `@treeseed/core` in the current project or run the CLI inside a Treeseed workspace."
+      );
+    }
+  }
+  const packageRoot = dirname(packageJsonPath);
+  const sourceEntrypoint = resolve(packageRoot, "src", "agents", "cli.ts");
+  if (existsSync(sourceEntrypoint)) {
+    return pathToFileURL(sourceEntrypoint).href;
+  }
+  const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+  const exportedEntrypoint = packageJson.exports?.["./agent/cli"];
+  const distRelativePath = typeof exportedEntrypoint === "string" ? exportedEntrypoint : exportedEntrypoint?.default ?? "./dist/agents/cli.js";
+  return pathToFileURL(resolve(packageRoot, distRelativePath)).href;
+}
 const sdkOperationsRuntime = new SdkOperationsRuntime();
 function formatValidationError(spec, errors) {
   return [
@@ -148,7 +190,7 @@ class TreeseedOperationsSdk {
   }
   async executeAgents(argv, context) {
     try {
-      const { runTreeseedAgentCli } = await import("@treeseed/agent/cli");
+      const { runTreeseedAgentCli } = await import(resolveCoreAgentCliEntrypoint(context.cwd));
       return await runTreeseedAgentCli(argv, {
         cwd: context.cwd,
         env: context.env,
@@ -172,6 +214,10 @@ class TreeseedOperationsSdk {
     const argv = request.argv ?? [];
     const commandName = request.commandName;
     if (commandName === "agents") {
+      if (argv.some(isHelpFlag)) {
+        context.write(renderTreeseedHelp("agents"), "stdout");
+        return 0;
+      }
       return this.executeAgents(argv, context);
     }
     const spec = findTreeseedOperation(commandName);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@treeseed/cli",
-  "version": "0.4.6",
+  "version": "0.4.8",
   "description": "Operator-facing Treeseed CLI package.",
   "license": "AGPL-3.0-only",
   "repository": {
@@ -43,8 +43,7 @@
     "release:publish": "node ./scripts/run-ts.mjs ./scripts/publish-package.ts"
   },
   "dependencies": {
-    "@treeseed/agent": "^0.4.3",
-    "@treeseed/sdk": "^0.4.5"
+    "@treeseed/sdk": "^0.4.7"
   },
   "devDependencies": {
     "@types/node": "^24.6.0",