@treeseed/cli 0.1.1

package/dist/cli/handlers/work.js

@@ -0,0 +1,85 @@
+import {
+  assertCleanWorktree,
+  branchExists,
+  checkoutBranch,
+  currentManagedBranch,
+  ensureLocalBranchTracking,
+  gitWorkflowRoot,
+  remoteBranchExists,
+  syncBranchWithOrigin
+} from "../../scripts/git-workflow-lib.js";
+import { guidedResult } from "./utils.js";
+import { provisionBranchPreview } from "./start.js";
+import { handleStart } from "./start.js";
+import { resolveTreeseedWorkflowState } from "../workflow-state.js";
+const handleWork = async (invocation, context) => {
+  const commandName = invocation.commandName || "work";
+  const branchName = invocation.positionals[0];
+  const preview = invocation.args.preview === true;
+  const repoDir = gitWorkflowRoot(context.cwd);
+  const currentBranch = currentManagedBranch(context.cwd);
+  if (currentBranch === branchName) {
+    const state2 = resolveTreeseedWorkflowState(context.cwd);
+    if (preview && !state2.preview.enabled) {
+      return provisionBranchPreview(branchName, context, commandName);
+    }
+    return guidedResult({
+      command: commandName,
+      summary: `Already working on ${branchName}.`,
+      facts: [
+        { label: "Branch", value: branchName },
+        { label: "Preview", value: state2.preview.enabled ? "enabled" : "disabled" },
+        { label: "Preview URL", value: state2.preview.url ?? "(none)" }
+      ],
+      nextSteps: [
+        preview && !state2.preview.enabled ? `treeseed work ${branchName} --preview` : "treeseed dev",
+        'treeseed ship "describe your change"'
+      ],
+      report: {
+        branchName,
+        resumed: true,
+        preview: state2.preview.enabled,
+        previewUrl: state2.preview.url
+      }
+    });
+  }
+  if (!branchExists(repoDir, branchName) && !remoteBranchExists(repoDir, branchName)) {
+    return handleStart({
+      ...invocation,
+      commandName
+    }, context);
+  }
+  assertCleanWorktree(context.cwd);
+  ensureLocalBranchTracking(repoDir, branchName);
+  checkoutBranch(repoDir, branchName);
+  syncBranchWithOrigin(repoDir, branchName);
+  if (preview) {
+    const state2 = resolveTreeseedWorkflowState(context.cwd);
+    if (!state2.preview.enabled) {
+      return provisionBranchPreview(branchName, context, commandName);
+    }
+  }
+  const state = resolveTreeseedWorkflowState(context.cwd);
+  return guidedResult({
+    command: commandName,
+    summary: `Resumed feature branch ${branchName}.`,
+    facts: [
+      { label: "Branch", value: branchName },
+      { label: "Preview", value: state.preview.enabled ? "enabled" : "disabled" },
+      { label: "Preview URL", value: state.preview.url ?? "(none)" }
+    ],
+    nextSteps: [
+      state.preview.enabled ? `treeseed publish --target-branch ${branchName}` : "treeseed dev",
+      'treeseed ship "describe your change"'
+    ],
+    report: {
+      branchName,
+      resumed: true,
+      preview: state.preview.enabled,
+      previewUrl: state.preview.url
+    }
+  });
+};
+export {
+  handleWork
+};

package/dist/cli/help.js

@@ -0,0 +1,143 @@
+import { findCommandSpec, listCommandNames, TRESEED_COMMAND_SPECS } from "./registry.js";
+const GROUP_ORDER = [
+  "Workflow",
+  "Local Development",
+  "Validation",
+  "Release Utilities",
+  "Utilities",
+  "Passthrough"
+];
+function levenshtein(left, right) {
+  const rows = Array.from({ length: left.length + 1 }, () => new Array(right.length + 1).fill(0));
+  for (let i = 0; i <= left.length; i += 1) rows[i][0] = i;
+  for (let j = 0; j <= right.length; j += 1) rows[0][j] = j;
+  for (let i = 1; i <= left.length; i += 1) {
+    for (let j = 1; j <= right.length; j += 1) {
+      const cost = left[i - 1] === right[j - 1] ? 0 : 1;
+      rows[i][j] = Math.min(
+        rows[i - 1][j] + 1,
+        rows[i][j - 1] + 1,
+        rows[i - 1][j - 1] + cost
+      );
+    }
+  }
+  return rows[left.length][right.length];
+}
+function formatSection(title, lines) {
+  if (lines.length === 0) return "";
+  return `${title}
+${lines.join("\n")}`;
+}
+function groupedCommands() {
+  const groups = /* @__PURE__ */ new Map();
+  for (const group of GROUP_ORDER) groups.set(group, []);
+  for (const spec of TRESEED_COMMAND_SPECS) {
+    const entries = groups.get(spec.group) ?? [];
+    entries.push(spec);
+    groups.set(spec.group, entries);
+  }
+  return groups;
+}
+function renderUsage(spec) {
+  if (spec.usage) return spec.usage;
+  const args = (spec.arguments ?? []).map((arg) => arg.required ? `<${arg.name}>` : `[${arg.name}]`);
+  const options = (spec.options ?? []).map((option) => option.repeatable ? `[${option.flags}]...` : `[${option.flags}]`);
+  return ["treeseed", spec.name, ...args, ...options].join(" ").replace(/\s+/gu, " ").trim();
+}
+function suggestTreeseedCommands(input) {
+  const normalized = input.trim().toLowerCase();
+  if (!normalized) return [];
+  return listCommandNames().map((name) => ({ name, score: levenshtein(normalized, name) })).sort((left, right) => left.score - right.score || left.name.localeCompare(right.name)).slice(0, 3).map((entry) => entry.name);
+}
+function renderTreeseedHelp(commandName) {
+  if (!commandName) {
+    const groups = groupedCommands();
+    const primaryWorkflow = ["setup", "work", "dev", "ship", "publish", "promote", "rollback", "teardown"].map((name) => findCommandSpec(name)).filter((spec2) => Boolean(spec2));
+    const workflowGuidance = ["status", "next", "continue", "doctor"].map((name) => findCommandSpec(name)).filter((spec2) => Boolean(spec2));
+    const sections2 = [
+      "Treeseed CLI",
+      "Unified TypeScript command interface for Treeseed project setup, branch workflow, deployment, and release automation.",
+      "",
+      "Usage",
+      "  treeseed <command> [args...]",
+      "  treeseed help [command]",
+      "",
+      formatSection("Primary Workflow", primaryWorkflow.map((command) => {
+        const spacer = command.name.length < 18 ? " ".repeat(18 - command.name.length) : " ";
+        return `  ${command.name}${spacer}${command.summary}`;
+      })),
+      "",
+      formatSection("Workflow Guidance", workflowGuidance.map((command) => {
+        const spacer = command.name.length < 18 ? " ".repeat(18 - command.name.length) : " ";
+        return `  ${command.name}${spacer}${command.summary}`;
+      })),
+      "",
+      ...GROUP_ORDER.filter((group) => group !== "Workflow").map((group) => formatSection(group, (groups.get(group) ?? []).map((command) => {
+        const spacer = command.name.length < 18 ? " ".repeat(18 - command.name.length) : " ";
+        return `  ${command.name}${spacer}${command.summary}`;
+      }))).filter(Boolean),
+      "",
+      formatSection("Common Flows", [
+        "  treeseed setup",
+        "  treeseed work feature/my-change --preview",
+        '  treeseed ship "feat: describe your change"',
+        "  treeseed publish --environment staging",
+        "  treeseed promote --patch",
+        "  treeseed teardown"
+      ]),
+      "",
+      formatSection("Help", [
+        "  treeseed --help",
+        "  treeseed help publish",
+        "  treeseed publish --help"
+      ]),
+      "",
+      "Notes",
+      "  - Workspace-only commands must be run from a Treeseed workspace root.",
+      "  - Use `treeseed setup`, `treeseed work`, `treeseed ship`, `treeseed publish`, `treeseed promote`, and `treeseed teardown` for the simplified workflow.",
+      "  - `config`, `deploy`, `start`, `save`, `release`, `close`, and `destroy` remain available as compatibility commands.",
+      "  - Use `--json` on guidance and main workflow commands when an AI agent or script needs machine-readable output."
+    ];
+    return sections2.filter(Boolean).join("\n");
+  }
+  const spec = findCommandSpec(commandName);
+  if (!spec) {
+    const suggestions = suggestTreeseedCommands(commandName);
+    const lines = [`Unknown treeseed command: ${commandName}`];
+    if (suggestions.length > 0) {
+      lines.push(`Did you mean: ${suggestions.map((item) => `\`${item}\``).join(", ")}?`);
+    }
+    lines.push("Run `treeseed help` to see the full command list.");
+    return lines.join("\n");
+  }
+  const formatOptions = (spec.options ?? []).map((option) => {
+    const spacer = option.flags.length < 28 ? " ".repeat(28 - option.flags.length) : " ";
+    return `  ${option.flags}${spacer}${option.description}`;
+  });
+  const formatArguments = (spec.arguments ?? []).map((arg) => {
+    const rendered = arg.required ? `<${arg.name}>` : `[${arg.name}]`;
+    return `  ${rendered}  ${arg.description}`;
+  });
+  const sections = [
+    `${spec.name}  ${spec.summary}`,
+    spec.description,
+    "",
+    formatSection("Usage", [`  ${renderUsage(spec)}`]),
+    formatArguments.length > 0 ? `
+${formatSection("Arguments", formatArguments)}` : "",
+    formatOptions.length > 0 ? `
+${formatSection("Options", formatOptions)}` : "",
+    (spec.examples ?? []).length > 0 ? `
+${formatSection("Examples", spec.examples.map((example) => `  ${example}`))}` : "",
+    (spec.notes ?? []).length > 0 ? `
+${formatSection("Notes", spec.notes.map((note) => `  - ${note}`))}` : "",
+    (spec.related ?? []).length > 0 ? `
+Related: ${spec.related.map((item) => `\`${item}\``).join(", ")}` : ""
+  ];
+  return sections.filter(Boolean).join("\n");
+}
+export {
+  renderTreeseedHelp,
+  renderUsage,
+  suggestTreeseedCommands
+};

package/dist/cli/main.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+import { fileURLToPath } from "node:url";
+import { resolve } from "node:path";
+import { runTreeseedCli } from "./runtime.js";
+import { runTreeseedCli as runTreeseedCli2, executeTreeseedCommand, createTreeseedCommandContext } from "./runtime.js";
+import { renderTreeseedHelp, renderUsage, suggestTreeseedCommands } from "./help.js";
+import { findCommandSpec, listCommandNames, TRESEED_COMMAND_SPECS } from "./registry.js";
+import { parseTreeseedInvocation, validateTreeseedInvocation } from "./parser.js";
+const currentFile = fileURLToPath(import.meta.url);
+const entryFile = resolve(process.argv[1] ?? "");
+if (entryFile === currentFile) {
+  const exitCode = await runTreeseedCli(process.argv.slice(2));
+  process.exit(exitCode);
+}
+export {
+  TRESEED_COMMAND_SPECS,
+  createTreeseedCommandContext,
+  executeTreeseedCommand,
+  findCommandSpec,
+  listCommandNames,
+  parseTreeseedInvocation,
+  renderTreeseedHelp,
+  renderUsage,
+  runTreeseedCli2 as runTreeseedCli,
+  suggestTreeseedCommands,
+  validateTreeseedInvocation
+};

package/dist/cli/parser.js

@@ -0,0 +1,96 @@
+function optionKey(spec) {
+  return spec.name;
+}
+function parseTreeseedInvocation(command, argv) {
+  const args = {};
+  const positionals = [];
+  const options = new Map((command.options ?? []).map((spec) => [spec.name, spec]));
+  const byFlag = /* @__PURE__ */ new Map();
+  for (const spec of options.values()) {
+    const firstToken = spec.flags.split(/[ ,|]+/).find((token) => token.startsWith("--") || token.startsWith("-"));
+    if (firstToken) byFlag.set(firstToken, spec);
+  }
+  const rest = [...argv];
+  while (rest.length > 0) {
+    const current = rest.shift();
+    if (current === "--") {
+      positionals.push(...rest);
+      break;
+    }
+    if (current.startsWith("-")) {
+      const [flag, inlineValue] = current.split("=", 2);
+      const spec = byFlag.get(flag);
+      if (!spec) {
+        throw new Error(`Unknown option: ${flag}`);
+      }
+      if (spec.kind === "boolean") {
+        args[optionKey(spec)] = true;
+        continue;
+      }
+      const value = inlineValue ?? rest.shift();
+      if (!value) {
+        throw new Error(`Missing value for ${flag}`);
+      }
+      if (spec.kind === "enum" && spec.values && !spec.values.includes(value)) {
+        throw new Error(`Invalid value for ${flag}: ${value}. Expected one of ${spec.values.join(", ")}.`);
+      }
+      if (spec.repeatable) {
+        const currentValues = Array.isArray(args[optionKey(spec)]) ? args[optionKey(spec)] : [];
+        args[optionKey(spec)] = [...currentValues, value];
+      } else {
+        args[optionKey(spec)] = value;
+      }
+      continue;
+    }
+    positionals.push(current);
+  }
+  const messageTailArg = (command.arguments ?? []).find((arg) => arg.kind === "message_tail");
+  if (messageTailArg && positionals.length > 1) {
+    const [first, ...restPositional] = positionals;
+    return {
+      commandName: command.name,
+      args,
+      positionals: first ? [first, ...restPositional] : restPositional,
+      rawArgs: argv
+    };
+  }
+  return {
+    commandName: command.name,
+    args,
+    positionals,
+    rawArgs: argv
+  };
+}
+function validateTreeseedInvocation(command, invocation) {
+  const errors = [];
+  const args = command.arguments ?? [];
+  const positionals = [...invocation.positionals];
+  for (const arg of args) {
+    if (arg.kind === "message_tail") {
+      if (positionals.join(" ").trim().length === 0 && arg.required) {
+        errors.push(`Missing required argument: ${arg.name}`);
+      }
+      continue;
+    }
+    const next = positionals.shift();
+    if (!next && arg.required) {
+      errors.push(`Missing required argument: ${arg.name}`);
+    }
+  }
+  if (command.name === "release" || command.name === "promote") {
+    const selected = ["major", "minor", "patch"].filter((name) => invocation.args[name] === true);
+    if (selected.length !== 1) {
+      errors.push(`Treeseed ${command.name} requires exactly one version bump flag: --major, --minor, or --patch.`);
+    }
+  }
+  if (command.name === "deploy" || command.name === "publish") {
+    if (!invocation.args.environment && !invocation.args.targetBranch && !process.env.CI) {
+      errors.push(`Treeseed ${command.name} requires \`--environment local|staging|prod\` or \`--target-branch <branch>\` outside CI.`);
+    }
+  }
+  return errors;
+}
+export {
+  parseTreeseedInvocation,
+  validateTreeseedInvocation
+};