@bvdm/delano 0.1.0

package/src/cli/commands/install.js

@@ -0,0 +1,57 @@
+const {
+  applyInstallPlan,
+  buildInstallPlan,
+  collectConflicts,
+  confirmInstall,
+  parseInstallArgs,
+  printConflicts,
+  printPlanSummary
+} = require("../lib/install");
+
+function getInstallHelp() {
+  return [
+    "Usage:",
+    "  delano install [options]",
+    "",
+    "Options:",
+    "  --target <dir>     Install into the given directory. Defaults to the current working directory.",
+    "  --agents <list>    Comma-separated agent list for future opt-in adapter docs: claude,codex,opencode,pi.",
+    "  --force            Overwrite existing allowlisted target paths. Does not override parent-path blockers.",
+    "  --yes              Skip the final confirmation prompt.",
+    "  -h, --help         Show command help.",
+    "",
+    "Behavior:",
+    "  - Computes the full install plan before writing files.",
+    "  - Aborts on conflicts by default.",
+    "  - Only installs the approved base payload; top-level adapter entry docs remain opt-in and are not installed in v1."
+  ].join("\n");
+}
+
+async function runInstall(args) {
+  const options = parseInstallArgs(args);
+  const plan = buildInstallPlan(options);
+  const conflicts = collectConflicts(plan);
+  const unforceableConflicts = conflicts.filter((conflict) => !conflict.forceable);
+  const blockingConflicts = options.force ? unforceableConflicts : conflicts;
+
+  printPlanSummary(plan, options);
+
+  if (blockingConflicts.length > 0) {
+    printConflicts(blockingConflicts, options);
+    return 1;
+  }
+
+  const confirmed = await confirmInstall(plan, options);
+  if (!confirmed) {
+    console.error("Install canceled.");
+    return 1;
+  }
+
+  applyInstallPlan(plan, options);
+  return 0;
+}
+
+module.exports = {
+  getInstallHelp,
+  runInstall
+};

package/src/cli/commands/wrapper.js

@@ -0,0 +1,26 @@
+const { runPmScript } = require("../lib/pm");
+
+function createWrapperCommand(scriptName) {
+  return {
+    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);
+    },
+    help() {
+      return [
+        "Usage:",
+        `  delano ${scriptName} [-- <script-args>]`,
+        "",
+        "Behavior:",
+        `  - 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");
+    }
+  };
+}
+
+module.exports = {
+  createWrapperCommand
+};

package/src/cli/index.js

@@ -0,0 +1,97 @@
+const { readFileSync } = require("node:fs");
+const path = require("node:path");
+
+const { CliError } = require("./lib/errors");
+const { getPackageRoot } = require("./lib/runtime");
+const { runInstall, getInstallHelp } = require("./commands/install");
+const { createWrapperCommand } = require("./commands/wrapper");
+
+const wrapperCommands = {
+  init: createWrapperCommand("init"),
+  validate: createWrapperCommand("validate"),
+  status: createWrapperCommand("status"),
+  next: createWrapperCommand("next")
+};
+
+const commands = {
+  install: {
+    description: "Install the approved Delano runtime payload into a target repository.",
+    run: runInstall,
+    help: getInstallHelp
+  },
+  init: wrapperCommands.init,
+  validate: wrapperCommands.validate,
+  status: wrapperCommands.status,
+  next: wrapperCommands.next
+};
+
+function getPackageVersion() {
+  const packageJsonPath = path.join(getPackageRoot(), "package.json");
+  const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+  return packageJson.version;
+}
+
+function getGeneralHelp() {
+  return [
+    "Delano CLI",
+    "",
+    "Usage:",
+    "  delano <command> [options]",
+    "",
+    "Commands:",
+    "  install    Install the approved Delano runtime payload",
+    "  init       Run .agents/scripts/pm/init.sh in the current Delano repo",
+    "  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",
+    "",
+    "Global options:",
+    "  -h, --help      Show help",
+    "  -v, --version   Show version",
+    "",
+    "Examples:",
+    "  delano install --target ../my-repo --yes",
+    "  delano validate",
+    "  delano next -- --all",
+    "",
+    "Use 'delano <command> --help' for command-specific help."
+  ].join("\n");
+}
+
+async function run(argv) {
+  if (argv.length === 0) {
+    console.log(getGeneralHelp());
+    return 0;
+  }
+
+  const [commandName, ...commandArgs] = argv;
+
+  if (commandName === "-h" || commandName === "--help" || commandName === "help") {
+    console.log(getGeneralHelp());
+    return 0;
+  }
+
+  if (commandName === "-v" || commandName === "--version" || commandName === "version") {
+    console.log(getPackageVersion());
+    return 0;
+  }
+
+  const command = commands[commandName];
+  if (!command) {
+    throw new CliError(`Unknown command: ${commandName}\n\n${getGeneralHelp()}`, 1);
+  }
+
+  if (commandArgs.includes("--help") || commandArgs.includes("-h")) {
+    const helpText = typeof command.help === "function" ? command.help() : getGeneralHelp();
+    console.log(helpText);
+    return 0;
+  }
+
+  return command.run(commandArgs);
+}
+
+module.exports = {
+  commands,
+  getGeneralHelp,
+  run
+};

package/src/cli/lib/errors.js

@@ -0,0 +1,11 @@
+class CliError extends Error {
+  constructor(message, exitCode = 1) {
+    super(message);
+    this.name = "CliError";
+    this.exitCode = exitCode;
+  }
+}
+
+module.exports = {
+  CliError
+};

package/src/cli/lib/install.js

@@ -0,0 +1,261 @@
+const {
+  chmodSync,
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  statSync,
+} = require("node:fs");
+const path = require("node:path");
+const readline = require("node:readline/promises");
+const { stdin, stdout } = require("node:process");
+
+const { CliError } = require("./errors");
+const { getPackageRoot, getPathType } = require("./runtime");
+
+const SUPPORTED_AGENTS = ["claude", "codex", "opencode", "pi"];
+
+function readInstallManifest() {
+  const manifestPath = path.join(getPackageRoot(), "assets", "install-manifest.json");
+  const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+  return {
+    manifestPath,
+    manifest,
+    payloadRoot: path.join(getPackageRoot(), "assets", "payload")
+  };
+}
+
+function parseAgentList(rawValue) {
+  if (!rawValue) {
+    return [...SUPPORTED_AGENTS];
+  }
+
+  const selected = [];
+  for (const chunk of rawValue.split(",")) {
+    const value = chunk.trim().toLowerCase();
+    if (!value) {
+      continue;
+    }
+    if (!SUPPORTED_AGENTS.includes(value)) {
+      throw new CliError(
+        `Unknown agent '${value}'. Supported values: ${SUPPORTED_AGENTS.join(", ")}.`,
+        1
+      );
+    }
+    if (!selected.includes(value)) {
+      selected.push(value);
+    }
+  }
+
+  if (selected.length === 0) {
+    throw new CliError("No agents selected. Pass --agents claude,codex,opencode,pi or omit the flag.", 1);
+  }
+
+  return selected;
+}
+
+function parseInstallArgs(args) {
+  const options = {
+    target: process.cwd(),
+    force: false,
+    yes: false,
+    agents: [...SUPPORTED_AGENTS]
+  };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+
+    if (arg === "--target") {
+      index += 1;
+      if (!args[index]) {
+        throw new CliError("Missing value for --target.", 1);
+      }
+      options.target = args[index];
+      continue;
+    }
+
+    if (arg.startsWith("--target=")) {
+      options.target = arg.slice("--target=".length);
+      continue;
+    }
+
+    if (arg === "--agents") {
+      index += 1;
+      if (!args[index]) {
+        throw new CliError("Missing value for --agents.", 1);
+      }
+      options.agents = parseAgentList(args[index]);
+      continue;
+    }
+
+    if (arg.startsWith("--agents=")) {
+      options.agents = parseAgentList(arg.slice("--agents=".length));
+      continue;
+    }
+
+    if (arg === "--force") {
+      options.force = true;
+      continue;
+    }
+
+    if (arg === "--yes") {
+      options.yes = true;
+      continue;
+    }
+
+    throw new CliError(`Unknown install option: ${arg}`, 1);
+  }
+
+  options.target = path.resolve(options.target);
+  return options;
+}
+
+function buildInstallPlan(options) {
+  const { manifest, payloadRoot } = readInstallManifest();
+  const items = manifest.paths.map((relativePath) => {
+    const sourcePath = path.join(payloadRoot, relativePath);
+    if (!existsSync(sourcePath)) {
+      throw new CliError(
+        `Packaged asset missing for '${relativePath}'. Run 'npm run build:assets' before using 'delano install' from a source checkout.`,
+        1
+      );
+    }
+
+    return {
+      relativePath,
+      sourcePath,
+      targetPath: path.join(options.target, relativePath)
+    };
+  });
+
+  return {
+    manifest,
+    items,
+    targetRoot: options.target
+  };
+}
+
+function collectConflicts(plan) {
+  const conflicts = [];
+
+  for (const item of plan.items) {
+    let current = path.dirname(item.targetPath);
+    const targetRoot = path.parse(item.targetPath).root;
+
+    while (current && current !== targetRoot) {
+      const parentType = getPathType(current);
+      if (parentType && parentType !== "directory") {
+        conflicts.push({
+          relativePath: item.relativePath,
+          conflictPath: path.relative(plan.targetRoot, current) || current,
+          targetPath: current,
+          pathType: parentType,
+          reason: "a parent path exists as a non-directory and blocks install",
+          forceable: false
+        });
+        break;
+      }
+      current = path.dirname(current);
+    }
+
+    const exactType = getPathType(item.targetPath);
+    if (exactType) {
+      conflicts.push({
+        relativePath: item.relativePath,
+        conflictPath: item.relativePath,
+        targetPath: item.targetPath,
+        pathType: exactType,
+        reason: "target already exists and install would overwrite it",
+        forceable: true
+      });
+    }
+  }
+
+  return conflicts.sort((left, right) => {
+    if (left.relativePath === right.relativePath) {
+      return left.targetPath.localeCompare(right.targetPath);
+    }
+    return left.relativePath.localeCompare(right.relativePath);
+  });
+}
+
+function printPlanSummary(plan, options) {
+  console.log("Install plan");
+  console.log("------------");
+  console.log(`Target: ${options.target}`);
+  console.log(`Files: ${plan.items.length}`);
+  console.log(`Agents: ${options.agents.join(", ")}`);
+  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.");
+}
+
+function printConflicts(conflicts, options) {
+  console.error("");
+  console.error("Conflicts");
+  console.error("---------");
+  for (const conflict of conflicts) {
+    const forceLabel = conflict.forceable ? "forceable" : "not forceable";
+    console.error(
+      `- ${conflict.conflictPath} [${conflict.pathType}; ${forceLabel}]: ${conflict.reason} (target: ${conflict.relativePath})`
+    );
+  }
+  console.error("");
+  if (options.force) {
+    console.error("Install cannot continue because at least one conflict is not forceable.");
+  } else {
+    console.error("Install aborted before writing files. Re-run with --force to overwrite only allowlisted target paths.");
+  }
+}
+
+async function confirmInstall(plan, options) {
+  if (options.yes) {
+    return true;
+  }
+
+  const rl = readline.createInterface({ input: stdin, output: stdout });
+  try {
+    const prompt = options.force
+      ? `Proceed with force-installing ${plan.items.length} files into ${options.target}? [y/N] `
+      : `Proceed with installing ${plan.items.length} files into ${options.target}? [y/N] `;
+    const answer = await rl.question(prompt);
+    return /^[Yy](es)?$/.test(answer.trim());
+  } finally {
+    rl.close();
+  }
+}
+
+function applyInstallPlan(plan, options) {
+  for (const item of plan.items) {
+    const existingType = getPathType(item.targetPath);
+    if (existingType) {
+      rmSync(item.targetPath, { recursive: true, force: true });
+    }
+
+    mkdirSync(path.dirname(item.targetPath), { recursive: true });
+    copyFileSync(item.sourcePath, item.targetPath);
+    const sourceMode = statSync(item.sourcePath).mode & 0o777;
+    try {
+      chmodSync(item.targetPath, sourceMode);
+    } catch {
+      // Ignore mode-setting failures on platforms that do not preserve POSIX modes.
+    }
+  }
+
+  console.log("");
+  console.log(`Installed ${plan.items.length} files into ${options.target}.`);
+}
+
+module.exports = {
+  SUPPORTED_AGENTS,
+  applyInstallPlan,
+  buildInstallPlan,
+  collectConflicts,
+  confirmInstall,
+  parseAgentList,
+  parseInstallArgs,
+  printConflicts,
+  printPlanSummary,
+  readInstallManifest
+};

package/src/cli/lib/pm.js

@@ -0,0 +1,29 @@
+const path = require("node:path");
+
+const { CliError } = require("./errors");
+const { findDelanoRoot, runBashScript } = require("./runtime");
+
+function resolvePmScript(scriptName, startDir = process.cwd()) {
+  const repoRoot = findDelanoRoot(startDir);
+  if (!repoRoot) {
+    throw new CliError(
+      "Could not find a Delano repository from the current working directory. Run this inside a repo containing .project/ and .agents/scripts/pm/, or install Delano first.",
+      1
+    );
+  }
+
+  return {
+    repoRoot,
+    scriptPath: path.join(repoRoot, ".agents", "scripts", "pm", `${scriptName}.sh`)
+  };
+}
+
+function runPmScript(scriptName, args) {
+  const { repoRoot, scriptPath } = resolvePmScript(scriptName);
+  return runBashScript(scriptPath, args, { cwd: repoRoot });
+}
+
+module.exports = {
+  resolvePmScript,
+  runPmScript
+};

package/src/cli/lib/runtime.js

@@ -0,0 +1,122 @@
+const { existsSync, lstatSync } = require("node:fs");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+
+const { CliError } = require("./errors");
+
+function getPackageRoot() {
+  return path.resolve(__dirname, "../../..");
+}
+
+function getPathType(targetPath) {
+  try {
+    const stat = lstatSync(targetPath);
+    if (stat.isSymbolicLink()) {
+      return "symlink";
+    }
+    if (stat.isDirectory()) {
+      return "directory";
+    }
+    return "file";
+  } catch {
+    return null;
+  }
+}
+
+function findDelanoRoot(startDir = process.cwd()) {
+  let current = path.resolve(startDir);
+  const { root } = path.parse(current);
+
+  while (true) {
+    const hasRuntime = existsSync(path.join(current, ".agents", "scripts", "pm"));
+    const hasProject = existsSync(path.join(current, ".project"));
+    if (hasRuntime && hasProject) {
+      return current;
+    }
+
+    if (current === root) {
+      return null;
+    }
+
+    current = path.dirname(current);
+  }
+}
+
+function resolveBash() {
+  const candidates = [];
+
+  if (process.env.DELANO_BASH) {
+    candidates.push(process.env.DELANO_BASH);
+  }
+
+  if (process.platform === "win32") {
+    const whereResult = spawnSync("where.exe", ["bash"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    });
+
+    if (whereResult.status === 0 && whereResult.stdout) {
+      for (const line of whereResult.stdout.split(/\r?\n/)) {
+        if (line.trim()) {
+          candidates.push(line.trim());
+        }
+      }
+    }
+
+    candidates.push(
+      "C:\\Program Files\\Git\\usr\\bin\\bash.exe",
+      "C:\\Program Files\\Git\\bin\\bash.exe"
+    );
+  } else {
+    const whichResult = spawnSync("which", ["bash"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    });
+    if (whichResult.status === 0 && whichResult.stdout.trim()) {
+      candidates.push(whichResult.stdout.trim());
+    }
+    candidates.push("/usr/bin/bash", "/bin/bash");
+  }
+
+  for (const candidate of candidates) {
+    if (candidate && existsSync(candidate)) {
+      return candidate;
+    }
+  }
+
+  throw new CliError(
+    "Could not find a usable bash runtime. Install bash or set DELANO_BASH to its full path.",
+    1
+  );
+}
+
+function runBashScript(scriptPath, args, options = {}) {
+  const bashPath = resolveBash();
+  const result = spawnSync(bashPath, [scriptPath, ...args], {
+    cwd: options.cwd || process.cwd(),
+    stdio: "inherit",
+    env: options.env || process.env
+  });
+
+  if (result.error) {
+    throw new CliError(`Failed to launch bash for ${path.basename(scriptPath)}: ${result.error.message}`, 1);
+  }
+
+  return typeof result.status === "number" ? result.status : 1;
+}
+
+function ensureDirectoryPath(targetPath) {
+  const kind = getPathType(targetPath);
+  if (kind && kind !== "directory") {
+    throw new CliError(`${targetPath} exists as a ${kind}, but a directory is required.`, 1);
+  }
+}
+
+module.exports = {
+  ensureDirectoryPath,
+  findDelanoRoot,
+  getPackageRoot,
+  getPathType,
+  resolveBash,
+  runBashScript
+};