@bvdm/delano 0.2.3 → 0.2.5

package/src/cli/commands/wrapper.js

@@ -1,14 +1,20 @@
+const path = require("node:path");
+
 const { runPmScript } = require("../lib/pm");
 
-function createWrapperCommand(scriptName) {
+function createWrapperCommand(scriptName, options = {}) {
   return {
-    description: `Run .agents/scripts/pm/${scriptName}.sh in the current Delano repository.`,
+    description: options.description || `Run .agents/scripts/pm/${scriptName}.sh in the current Delano repository.`,
     run(args) {
       const passthrough = args[0] === "--" ? args.slice(1) : args;
-      return runPmScript(scriptName, passthrough);
+      return runPmScript(scriptName, normalizePassthrough(scriptName, passthrough));
     },
     help() {
-      return [
+      if (typeof options.help === "function") {
+        return options.help();
+      }
+
+      const lines = [
         "Usage:",
         `  delano ${scriptName} [-- <script-args>]`,
         "",
@@ -16,11 +22,29 @@ function createWrapperCommand(scriptName) {
         `  - Resolves the current Delano repository by searching upward for .project/ and .agents/scripts/pm/.`,
         `  - Runs .agents/scripts/pm/${scriptName}.sh through bash.`,
         "  - Pass '--' to make argument passthrough explicit when needed."
-      ].join("\n");
+      ];
+
+      if (scriptName === "status") {
+        lines.push(
+          "",
+          "Status examples:",
+          "  delano status --open --brief",
+          "  delano status -- --open --brief"
+        );
+      }
+
+      return lines.join("\n");
     }
   };
 }
 
+function normalizePassthrough(scriptName, args) {
+  if (scriptName !== "import-spec-kit" || args.length < 2 || path.isAbsolute(args[1])) {
+    return args;
+  }
+  return [args[0], path.resolve(process.cwd(), args[1]), ...args.slice(2)];
+}
+
 module.exports = {
   createWrapperCommand
 };

package/src/cli/index.js

@@ -7,9 +7,28 @@ const { getOnboardingHelp, runOnboarding } = require("./commands/onboarding");
 const { runInstall, getInstallHelp } = require("./commands/install");
 const { runViewer, getViewerHelp } = require("./commands/viewer");
 const { createWrapperCommand } = require("./commands/wrapper");
+const {
+  getProjectHelp,
+  getTaskHelp,
+  getUpdateHelp,
+  getWorkstreamHelp,
+  parseTaskArgs,
+  runProjectCommand,
+  runTaskCommand,
+  runUpdateCommand,
+  runWorkstreamCommand
+} = require("./commands/state");
 
 const wrapperCommands = {
   init: createWrapperCommand("init"),
+  "import-spec-kit": createWrapperCommand("import-spec-kit", {
+    description: "Create a planned Delano project from a Spec Kit-style markdown artifact.",
+    help: getImportSpecKitHelp
+  }),
+  research: createWrapperCommand("research", {
+    description: "Create repo-native research intake files for a Delano project.",
+    help: getResearchHelp
+  }),
   validate: createWrapperCommand("validate"),
   status: createWrapperCommand("status"),
   next: createWrapperCommand("next")
@@ -31,18 +50,36 @@ const commands = {
     run: runViewer,
     help: getViewerHelp
   },
+  project: {
+    description: "Create, show, and patch Delano project contracts.",
+    run: runProjectCommand,
+    help: getProjectHelp
+  },
+  workstream: {
+    description: "Add and patch Delano workstream contracts.",
+    run: runWorkstreamCommand,
+    help: getWorkstreamHelp
+  },
+  task: {
+    description: "Add and patch Delano task contracts with scoped lifecycle rollups.",
+    run: runTaskCommand,
+    help: getTaskHelp
+  },
+  update: {
+    description: "Add project progress updates from the project update template.",
+    run: runUpdateCommand,
+    help: getUpdateHelp
+  },
   init: wrapperCommands.init,
+  "import-spec-kit": wrapperCommands["import-spec-kit"],
+  research: wrapperCommands.research,
   validate: wrapperCommands.validate,
   status: wrapperCommands.status,
   next: wrapperCommands.next
 };
 
 function isInstallShorthand(argv) {
-  if (argv.length === 0) {
-    return false;
-  }
-
-  return argv[0].startsWith("-");
+  return argv.length > 0 && argv[0].startsWith("-");
 }
 
 function resolveInvocation(argv) {
@@ -99,8 +136,14 @@ function getGeneralHelp() {
     "  onboarding Analyze AGENTS.md with the approval-first onboarding skill",
     "  install    Install the approved Delano runtime payload",
     "  viewer     Launch the read-only local UI for .project contracts",
-    "  init       Run .agents/scripts/pm/init.sh in the current Delano repo",
-    "  validate   Run .agents/scripts/pm/validate.sh in the current Delano repo",
+    "  project    Create, show, and patch project contracts",
+    "  workstream Add and patch workstream contracts",
+    "  task       Add and patch task contracts with scoped lifecycle rollups",
+    "  update     Add a progress update from .project/templates",
+    "  init            Run .agents/scripts/pm/init.sh in the current Delano repo",
+    "  import-spec-kit Create a planned project from a Spec Kit-style markdown artifact",
+    "  research        Create repo-native research intake files for a project",
+    "  validate        Run .agents/scripts/pm/validate.sh in the current Delano repo",
     "  status     Run .agents/scripts/pm/status.sh in the current Delano repo",
     "  next       Run .agents/scripts/pm/next.sh in the current Delano repo",
     "",
@@ -115,7 +158,16 @@ function getGeneralHelp() {
     "  delano --target ../my-repo --yes",
     "  npx -y @bvdm/delano@latest --yes",
     "  delano viewer",
+    "  delano project create my-project --name \"My Project\" --owner team",
+    "  delano workstream add my-project WS-A --name \"API Foundation\" --owner backend-team",
+    "  delano task add my-project T-001 --name \"Build endpoint\" --workstream WS-A",
+    "  delano task start my-project T-001",
+    "  delano task close my-project T-001 --evidence \"Implemented and tested\"",
+    "  delano update add my-project --message \"Implemented endpoint smoke test\"",
+    "  delano import-spec-kit reminder-email-preferences docs/spec-kit/fixtures/minimal-spec-kit-project.md --json",
+    "  delano research my-project api-options --title \"API options\" --question \"Which API shape should we use?\" --json",
     "  delano validate",
+    "  delano status --open --brief",
     "  delano next -- --all",
     "",
     "Shorthand:",
@@ -128,6 +180,63 @@ function getGeneralHelp() {
   ].join("\n");
 }
 
+function getResearchHelp() {
+  return [
+    "Usage:",
+    "  delano research <project-slug> <research-slug> [options]",
+    "",
+    "Creates repo-native research intake files under .project/projects/<project-slug>/research/<research-slug>/, then runs Delano validation by default.",
+    "",
+    "Arguments:",
+    "  project-slug          Existing Delano project slug",
+    "  research-slug         Research folder slug in kebab-case",
+    "",
+    "Options:",
+    "  --title <title>        Human-readable research title",
+    "  --question <question>  Primary research question",
+    "  --owner <owner>        Research owner, defaults to team",
+    "  --no-validate          Create artifacts without running Delano validation",
+    "  --json                 Print a single machine-readable JSON result",
+    "  -h, --help             Show help",
+    "",
+    "Agent examples:",
+    "  delano research delano-spec-kit-interop import-edge-cases --title \"Import edge cases\" --question \"Which inputs should block import?\" --json",
+    "",
+    "Output:",
+    "  Human mode prints a concise summary plus validation output.",
+    "  JSON mode prints: { ok, command, project, research, files, validation }."
+  ].join("\n");
+}
+
+function getImportSpecKitHelp() {
+  return [
+    "Usage:",
+    "  delano import-spec-kit <slug> <source-md> [options]",
+    "",
+    "Creates a planned Delano project from the first supported Spec Kit-style markdown fixture, then runs Delano validation by default.",
+    "",
+    "Arguments:",
+    "  slug                  Target Delano project slug in kebab-case",
+    "  source-md             Path to the markdown source artifact",
+    "",
+    "Options:",
+    "  --name <project-name>  Project name override",
+    "  --owner <owner>        Project owner, defaults to team",
+    "  --lead <lead>          Project lead, defaults to owner",
+    "  --no-validate          Create artifacts without running Delano validation",
+    "  --json                 Print a single machine-readable JSON result",
+    "  -h, --help             Show help",
+    "",
+    "Agent examples:",
+    "  delano import-spec-kit reminder-email-preferences docs/spec-kit/fixtures/minimal-spec-kit-project.md --json",
+    "  delano import-spec-kit reminder-email-preferences input.md --name \"Reminder Email Preferences\" --owner platform --lead clark --json",
+    "",
+    "Output:",
+    "  Human mode prints a concise summary plus validation output.",
+    "  JSON mode prints: { ok, command, project, source, validation }."
+  ].join("\n");
+}
+
 async function run(argv) {
   const invocation = resolveInvocation(argv);
 
@@ -155,6 +264,10 @@ async function run(argv) {
 module.exports = {
   commands,
   getGeneralHelp,
+  getImportSpecKitHelp,
+  getResearchHelp,
+  getTaskHelp,
+  parseTaskArgs,
   resolveInvocation,
   run
 };

package/src/cli/lib/install.js

@@ -6,6 +6,7 @@ const {
   readFileSync,
   rmSync,
   statSync,
+  writeFileSync,
 } = require("node:fs");
 const path = require("node:path");
 const readline = require("node:readline");
@@ -14,8 +15,16 @@ const { stdin, stdout } = require("node:process");
 const { CliError } = require("./errors");
 const { getPackageRoot, getPathType } = require("./runtime");
 
+const CODEX_HOOKS_TARGET = ".codex/hooks.json";
+const CODEX_SESSION_STATUS_SCRIPT = ".agents/hooks/codex-session-status.js";
+
 const SUPPORTED_AGENTS = ["claude", "codex", "opencode", "pi"];
 const INSTALL_CATEGORIES = [
+  {
+    name: "codex-hooks",
+    description: ".codex hook configuration and SessionStart shim",
+    matches: (target) => target.startsWith(".codex/") || target === CODEX_SESSION_STATUS_SCRIPT
+  },
   {
     name: "agent-runtime",
     description: ".agents runtime except skills",
@@ -67,6 +76,8 @@ const INSTALL_CATEGORY_ALIASES = new Map([
   ["agent-skills", "skills"],
   ["agents", "agent-runtime"],
   ["runtime", "agent-runtime"],
+  ["codex", "codex-hooks"],
+  ["codex-config", "codex-hooks"],
   ["context", "project-context"],
   ["templates", "project-templates"],
   ["project-state", "project-projects"],
@@ -531,6 +542,9 @@ function collectConflicts(plan) {
 
     const exactType = getPathType(item.targetPath);
     if (exactType) {
+      if (isNonBlockingExistingTarget(item.relativePath)) {
+        continue;
+      }
       conflicts.push({
         relativePath: item.relativePath,
         conflictPath: item.relativePath,
@@ -566,6 +580,7 @@ function printPlanSummary(plan, options) {
   console.log(`Force: ${options.force ? "yes" : "no"}`);
   console.log("");
   console.log("Note: --agents is accepted now for forward compatibility, but v1 base install still excludes top-level adapter entry docs by default.");
+  console.log("Note: .codex/hooks.json is merged when it already exists, and Codex runs the hook only after hooks are enabled and trusted.");
   console.log("Note: .project/context, .project/projects, and .project/registry are repo-owned after install; use --no-project-state or --only for update-safe refreshes.");
 }
 
@@ -605,7 +620,20 @@ async function confirmInstall(plan, options) {
 }
 
 function applyInstallPlan(plan, options) {
+  let appliedCount = 0;
+  let skippedCount = 0;
+
   for (const item of plan.items) {
+    if (item.relativePath === CODEX_HOOKS_TARGET) {
+      const result = applyCodexHooksConfig(item);
+      if (result === "skipped") {
+        skippedCount += 1;
+      } else {
+        appliedCount += 1;
+      }
+      continue;
+    }
+
     const existingType = getPathType(item.targetPath);
     if (existingType) {
       rmSync(item.targetPath, { recursive: true, force: true });
@@ -619,13 +647,161 @@ function applyInstallPlan(plan, options) {
     } catch {
       // Ignore mode-setting failures on platforms that do not preserve POSIX modes.
     }
+    appliedCount += 1;
   }
 
   console.log("");
-  console.log(`Installed ${plan.items.length} files into ${options.target}.`);
+  console.log(`Installed or updated ${appliedCount} files into ${options.target}.`);
+  if (skippedCount > 0) {
+    console.log(`Skipped ${skippedCount} non-blocking file(s).`);
+  }
+  if (plan.items.some((item) => item.relativePath === CODEX_HOOKS_TARGET)) {
+    console.log("");
+    console.log("Codex hook config installed or merged at .codex/hooks.json.");
+    console.log("To activate it, enable Codex hooks, then approve the project and hook trust prompts.");
+    console.log("For one session, run: codex --enable hooks");
+    console.log("For persistent config, set [features].hooks = true in ~/.codex/config.toml.");
+  }
   console.log("Recommended next step: run 'delano onboarding' to review AGENTS.md. The command asks for explicit approval before analysis.");
 }
 
+function isNonBlockingExistingTarget(relativePath) {
+  return relativePath === CODEX_HOOKS_TARGET;
+}
+
+function applyCodexHooksConfig(item) {
+  const existingType = getPathType(item.targetPath);
+  if (!existingType) {
+    mkdirSync(path.dirname(item.targetPath), { recursive: true });
+    copyFileSync(item.sourcePath, item.targetPath);
+    applySourceMode(item.sourcePath, item.targetPath);
+    return "installed";
+  }
+
+  if (existingType !== "file") {
+    console.warn(`Skipped ${CODEX_HOOKS_TARGET}: existing ${existingType} cannot be merged safely.`);
+    return "skipped";
+  }
+
+  let existingConfig;
+  try {
+    existingConfig = readJsonFile(item.targetPath);
+  } catch (error) {
+    console.warn(`Skipped ${CODEX_HOOKS_TARGET}: existing file is not valid JSON (${error.message}).`);
+    return "skipped";
+  }
+
+  const packagedConfig = readJsonFile(item.sourcePath);
+  const mergeResult = mergeCodexHooksConfig(existingConfig, packagedConfig);
+  if (!mergeResult.ok) {
+    console.warn(`Skipped ${CODEX_HOOKS_TARGET}: ${mergeResult.reason}`);
+    return "skipped";
+  }
+
+  if (mergeResult.changed) {
+    writeFileSync(item.targetPath, `${JSON.stringify(mergeResult.config, null, 2)}\n`, "utf8");
+    return "merged";
+  }
+
+  return "unchanged";
+}
+
+function mergeCodexHooksConfig(existingConfig, packagedConfig) {
+  if (!isPlainObject(existingConfig)) {
+    return { ok: false, reason: "existing config must be a JSON object." };
+  }
+  if (!isPlainObject(packagedConfig) || !isPlainObject(packagedConfig.hooks)) {
+    throw new CliError("Packaged .codex/hooks.json is missing a hooks object.", 1);
+  }
+
+  const packagedSessionStart = packagedConfig.hooks.SessionStart;
+  if (!Array.isArray(packagedSessionStart)) {
+    throw new CliError("Packaged .codex/hooks.json is missing hooks.SessionStart.", 1);
+  }
+
+  const nextConfig = deepClone(existingConfig);
+  if (nextConfig.hooks === undefined) {
+    nextConfig.hooks = {};
+  }
+  if (!isPlainObject(nextConfig.hooks)) {
+    return { ok: false, reason: "existing hooks field must be a JSON object." };
+  }
+  if (nextConfig.hooks.SessionStart === undefined) {
+    nextConfig.hooks.SessionStart = [];
+  }
+  if (!Array.isArray(nextConfig.hooks.SessionStart)) {
+    return { ok: false, reason: "existing hooks.SessionStart field must be an array." };
+  }
+
+  let changed = false;
+  for (const desiredGroup of packagedSessionStart) {
+    if (!hasDelanoSessionStatusHook(nextConfig.hooks.SessionStart, desiredGroup)) {
+      nextConfig.hooks.SessionStart.push(deepClone(desiredGroup));
+      changed = true;
+    }
+  }
+
+  return {
+    ok: true,
+    changed,
+    config: nextConfig
+  };
+}
+
+function hasDelanoSessionStatusHook(sessionStartGroups, desiredGroup) {
+  const desiredCommands = collectHookCommands([desiredGroup]);
+  for (const group of sessionStartGroups) {
+    const commands = collectHookCommands([group]);
+    if (commands.some((command) => command.includes("codex-session-status.js"))) {
+      return true;
+    }
+    if (commands.some((command) => desiredCommands.includes(command))) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function collectHookCommands(groups) {
+  const commands = [];
+  for (const group of groups) {
+    if (!group || !Array.isArray(group.hooks)) {
+      continue;
+    }
+    for (const hook of group.hooks) {
+      if (hook && typeof hook.command === "string") {
+        commands.push(hook.command);
+      }
+    }
+  }
+  return commands;
+}
+
+function applySourceMode(sourcePath, targetPath) {
+  const sourceMode = statSync(sourcePath).mode & 0o777;
+  try {
+    chmodSync(targetPath, sourceMode);
+  } catch {
+    // Ignore mode-setting failures on platforms that do not preserve POSIX modes.
+  }
+}
+
+function deepClone(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function readJsonFile(filePath) {
+  return JSON.parse(stripByteOrderMark(readFileSync(filePath, "utf8")));
+}
+
+function stripByteOrderMark(text) {
+  return text.charCodeAt(0) === 0xFEFF ? text.slice(1) : text;
+}
+
 function normalizeManifestEntries(rawManifest) {
   const entries = Array.isArray(rawManifest.files) ? rawManifest.files : rawManifest.paths;
   if (!Array.isArray(entries)) {
@@ -686,5 +862,6 @@ module.exports = {
   printConflicts,
   printPlanSummary,
   readInstallManifest,
-  getMissingPackagedAssetMessage
+  getMissingPackagedAssetMessage,
+  mergeCodexHooksConfig
 };