@treeseed/cli 0.6.13 → 0.6.15

package/dist/cli/handlers/dev.js

@@ -43,14 +43,37 @@ function resolveCoreDevEntrypoint(cwd) {
 const handleDev = async (invocation, context) => {
   try {
     const watch = invocation.commandName === "dev:watch" || invocation.args.watch === true;
+    const passthroughArgs = [];
+    const forwardStringOption = (name, flag) => {
+      const value = invocation.args[name];
+      if (typeof value === "string" && value.trim().length > 0) {
+        passthroughArgs.push(flag, value);
+      }
+    };
+    const forwardBooleanOption = (name, flag) => {
+      if (invocation.args[name] === true) {
+        passthroughArgs.push(flag);
+      }
+    };
+    forwardStringOption("surface", "--surface");
+    forwardStringOption("host", "--host");
+    forwardStringOption("port", "--port");
+    forwardStringOption("apiHost", "--api-host");
+    forwardStringOption("apiPort", "--api-port");
+    forwardStringOption("managerPort", "--manager-port");
+    forwardStringOption("setup", "--setup");
+    forwardStringOption("feedback", "--feedback");
+    forwardStringOption("open", "--open");
+    forwardBooleanOption("plan", "--plan");
+    forwardBooleanOption("json", "--json");
     const workspaceRoot = findNearestTreeseedWorkspaceRoot(context.cwd);
     const workspaceLinksMode = typeof invocation.args.workspaceLinks === "string" ? invocation.args.workspaceLinks : void 0;
     const workspaceLinks = workspaceRoot ? ensureLocalWorkspaceLinks(workspaceRoot, { env: context.env, mode: workspaceLinksMode }) : null;
-    if (workspaceLinks?.created.length) {
+    if (workspaceLinks?.created.length && invocation.args.json !== true) {
       context.write(`[workspace][link] Linked ${workspaceLinks.created.length} local workspace package paths.`, "stdout");
     }
     const resolved = resolveCoreDevEntrypoint(context.cwd);
-    const args = watch ? [...resolved.args, "--watch"] : resolved.args;
+    const args = watch ? [...resolved.args, ...passthroughArgs, "--watch"] : [...resolved.args, ...passthroughArgs];
     const result = context.spawn(resolved.command, args, {
       cwd: context.cwd,
       env: resolveTreeseedLaunchEnvironment({
@@ -62,6 +85,7 @@ const handleDev = async (invocation, context) => {
     });
     return {
       exitCode: result.status ?? 1,
+      suppressJsonResult: invocation.args.json === true,
       report: {
         command: "dev",
         ok: (result.status ?? 1) === 0,

package/dist/cli/handlers/utils.js

@@ -49,6 +49,9 @@ function guidedResult(options) {
 }
 function writeResult(result, context) {
   if (context.outputFormat === "json") {
+    if (result.suppressJsonResult === true) {
+      return result.exitCode ?? 0;
+    }
     const payload = result.report ?? {
       ok: (result.exitCode ?? 0) === 0,
       stdout: result.stdout ?? [],

package/dist/cli/operations-registry.js

@@ -20,6 +20,21 @@ function detail(name, detailText) {
 function related(name, why) {
   return { name, why };
 }
+const DEV_RUNTIME_OPTIONS = [
+  { name: "surface", flags: "--surface <surface>", description: "Select the local dev surface to run.", kind: "enum", values: ["integrated", "web", "api", "manager", "worker", "services"] },
+  { name: "host", flags: "--host <host>", description: "Host for the web dev server.", kind: "string" },
+  { name: "port", flags: "--port <port>", description: "Port for the web dev server.", kind: "string" },
+  { name: "apiHost", flags: "--api-host <host>", description: "Host used to construct the local API URL.", kind: "string" },
+  { name: "apiPort", flags: "--api-port <port>", description: "Port for the local API server.", kind: "string" },
+  { name: "managerPort", flags: "--manager-port <port>", description: "Port used for the local manager service URL.", kind: "string" },
+  { name: "setup", flags: "--setup <mode>", description: "Control automatic local runtime setup.", kind: "enum", values: ["auto", "check", "off"] },
+  { name: "feedback", flags: "--feedback <mode>", description: "Control live feedback, service restarts, and browser reload stamps.", kind: "enum", values: ["live", "restart", "off"] },
+  { name: "open", flags: "--open <mode>", description: "Control whether dev opens the browser after readiness.", kind: "enum", values: ["auto", "on", "off"] },
+  { name: "plan", flags: "--plan", description: "Print the dev runtime plan and exit without starting services.", kind: "boolean" },
+  { name: "json", flags: "--json", description: "Emit structured JSON or newline-delimited dev events.", kind: "boolean" },
+  { name: "watch", flags: "--watch", description: "Enable live watch behavior. `dev` defaults to live feedback; this remains for compatibility.", kind: "boolean" },
+  { name: "workspaceLinks", flags: "--workspace-links <mode>", description: "Control local workspace package links.", kind: "enum", values: ["auto", "off"] }
+];
 function genericWorkflowPosition(spec) {
   if (spec.group === "Workflow") {
     if (spec.name === "switch") return "start work";
@@ -1036,31 +1051,45 @@ const CLI_COMMAND_OVERLAYS = /* @__PURE__ */ new Map([
     handlerName: "destroy"
   })],
   ["dev", command({
-    options: [
-      { name: "workspaceLinks", flags: "--workspace-links <mode>", description: "Control local workspace package links.", kind: "enum", values: ["auto", "off"] }
-    ],
-    examples: ["treeseed dev"],
+    options: DEV_RUNTIME_OPTIONS,
+    examples: ["treeseed dev", "treeseed dev --plan --json", "treeseed dev --surface web --port 4322 --open off"],
     help: {
-      longSummary: ["Dev starts the unified local Treeseed runtime so you can work against the integrated web, API, and supporting local surfaces."],
+      longSummary: [
+        "Dev starts the unified local Treeseed runtime as a foreground supervisor so you can work against the integrated web, API, and supporting local surfaces.",
+        "The command keeps streaming logs and dev events until you press Ctrl+C, receive SIGTERM, or a required surface fails; shutdown stops every service process group it started."
+      ],
+      beforeYouRun: [
+        "Run from the tenant or workspace root you want to develop.",
+        "Use `--plan --json` when you want to inspect commands, setup steps, readiness checks, and watched paths without starting services.",
+        "Keep the foreground process running while you test. Press Ctrl+C to stop the supervised stack and free the local ports."
+      ],
       examples: [
-        example("treeseed dev", "Start integrated local development", "Run the default integrated local runtime."),
+        example("treeseed dev", "Start integrated local development", "Run the default integrated local runtime and keep supervising it in the foreground."),
+        example("treeseed dev --plan --json", "Inspect the runtime plan", "Emit a structured plan with setup steps, commands, ports, URLs, readiness checks, and watch entries."),
+        example("treeseed dev --surface web --port 4322 --open off", "Run only the web surface", "Start the Astro UI on a specific port without opening a browser."),
         example("trsd dev", "Use the short alias", "Start the same local runtime through the shorter entrypoint."),
-        example("treeseed dev && treeseed status", "Pair runtime start with orientation", "Start the local runtime and then inspect workflow state in another shell.")
+        example("treeseed dev --json", "Stream dev events", "Emit newline-delimited events while the long-running dev process supervises local services.")
+      ],
+      outcomes: [
+        "Starts the selected local surfaces, waits for readiness, and then remains attached as the live supervisor.",
+        "Stops watchers first and then terminates service process groups when the foreground command exits."
       ]
     },
     executionMode: "handler",
     handlerName: "dev"
   })],
   ["dev:watch", command({
-    options: [
-      { name: "workspaceLinks", flags: "--workspace-links <mode>", description: "Control local workspace package links.", kind: "enum", values: ["auto", "off"] }
-    ],
-    examples: ["treeseed dev:watch"],
+    options: DEV_RUNTIME_OPTIONS,
+    examples: ["treeseed dev:watch", "treeseed dev:watch --json"],
     help: {
-      longSummary: ["Dev:watch starts local development with rebuild and watch semantics so code changes are reflected continuously during active development."],
+      longSummary: [
+        "Dev:watch is a compatibility alias for foreground dev supervision with live feedback enabled.",
+        "It stays attached to the terminal and cleans up supervised services on Ctrl+C just like `dev`."
+      ],
       examples: [
-        example("treeseed dev:watch", "Start watch mode", "Run the local runtime with watch and rebuild behavior enabled."),
+        example("treeseed dev:watch", "Start watch mode", "Run the local runtime with watch and rebuild behavior enabled in the foreground."),
         example("trsd dev:watch", "Use the short alias", "Start the same watch-mode runtime through the shorter entrypoint."),
+        example("treeseed dev:watch --feedback restart", "Restart services without browser reload", "Use watcher-driven service restarts while leaving browser refresh to your own tooling."),
         example("treeseed dev:watch --help", "Inspect watch help", "Read the help surface before starting a longer watch session.")
       ]
     },

package/dist/cli/operations-types.d.ts

@@ -59,6 +59,7 @@ export type TreeseedCommandResult = {
     stdout?: string[];
     stderr?: string[];
     report?: Record<string, unknown> | null;
+    suppressJsonResult?: boolean;
 };
 export type TreeseedWriter = NonNullable<SdkOperationContext['write']>;
 export type TreeseedSpawner = NonNullable<SdkOperationContext['spawn']>;

package/dist/cli/runtime.d.ts

@@ -6,6 +6,7 @@ export declare function writeTreeseedResult(result: TreeseedOperationResult | {
     stdout?: string[];
     stderr?: string[];
     report?: Record<string, unknown> | null;
+    suppressJsonResult?: boolean;
 }, context: TreeseedCommandContext): number;
 export type TreeseedOperationsSdkOptions = {
     resolveHandler?: TreeseedHandlerResolver;

package/dist/cli/runtime.js

@@ -137,6 +137,9 @@ function createTreeseedCommandContext(overrides = {}) {
 }
 function writeTreeseedResult(result, context) {
   if (context.outputFormat === "json") {
+    if (result.suppressJsonResult === true) {
+      return result.exitCode ?? 0;
+    }
     const payload = result.report ?? {
       ok: (result.exitCode ?? 0) === 0,
       stdout: result.stdout ?? [],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@treeseed/cli",
-  "version": "0.6.13",
+  "version": "0.6.15",
   "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.13",
+    "@treeseed/sdk": "0.6.15",
     "ink": "^7.0.0",
     "react": "^19.2.5"
   },