@bvdm/delano 0.1.0 → 0.1.1

package/README.md

@@ -1,122 +1,124 @@
 # Delano
 
-Delano is an agent-agnostic, runtime-guided, skill-driven delivery system.
+Delano is an agent-agnostic delivery runtime. It keeps planning, execution, and evidence on disk so teams can work with different coding agents without changing the operating model every time.
 
-## WHY
+## What Delano is
 
-AI-assisted delivery is fast, but it easily becomes inconsistent.
+- `HANDBOOK.md` is the canonical operating model.
+- `.project/` is the delivery source of truth.
+- `.agents/` is the shared runtime: scripts, rules, hooks, skills, and adapters.
+- `.claude/` is a compatibility mirror of `.agents/`, not a second runtime.
+- `.delano/` is an optional UI layer.
 
-Delano exists to keep teams fast **and** reliable by giving one shared way to move from business outcomes to specs, tasks, code, and evidence.
+The npm package is intentionally thin. It distributes the approved runtime payload and wraps the existing shell-based PM scripts. It does not replace the handbook, the file contracts, or the underlying bash/Python execution layer.
 
-It is designed to reduce:
-- execution drift between planning and implementation
-- tool-specific lock-in
-- undocumented decisions and low-trust delivery flow
+## Delano CLI
 
-## WHAT
+- Package: `@bvdm/delano`
+- Binary: `delano`
+- Commands: `install`, `init`, `validate`, `status`, `next`
+- Primary v1.1 goal: bootstrap a repo safely, then stay out of the way
 
-Delano is a spec-first runtime for software delivery, backed by explicit file contracts and deterministic scripts.
+## One-command bootstrap
 
-Core pieces:
-- `HANDBOOK.md` — canonical operating model and governance
-- `.project/` — delivery truth (projects, tasks, context, updates, decisions)
-- `.agents/` — shared runtime (scripts, rules, hooks, skills, adapters)
-- `.claude/` — compatibility mirror for Claude-style paths (symlink where supported, directory mirror otherwise)
-- `.delano/` — optional UI layer
+To install the approved Delano runtime into the current repository:
 
-Probe-aware delivery is part of the operating model: draft the spec, make the probe decision explicit, and only approve once uncertainty is retired or consciously accepted.
+```bash
+npx -y @bvdm/delano@latest --yes
+```
 
-Supported adapters:
-- Claude Code
-- Codex CLI
-- OpenCode
-- Pi coding agent
+That shorthand is equivalent to:
 
-## HOW
+```bash
+npx -y @bvdm/delano@latest install --yes
+```
 
-### Quick start (inside a Delano repo)
+To install into a different directory:
 
 ```bash
-# 1) Validate the runtime and required assets
-bash .agents/scripts/pm/validate.sh
-
-# 2) Create a new delivery project scaffold
-bash .agents/scripts/pm/init.sh <slug> "<Project Name>" <owner> <lead>
+npx -y @bvdm/delano@latest --target /path/to/repo --yes
+```
 
-# 3) See portfolio/project status
-bash .agents/scripts/pm/status.sh
+If you already have the package installed locally, the same flow is:
 
-# 4) Get next executable tasks
-bash .agents/scripts/pm/next.sh
+```bash
+delano --yes
+delano --target /path/to/repo --yes
 ```
 
-### CLI v1 (current package work)
+## How to use Delano after install
 
-Delano now has a thin npm CLI layer with:
-- package name `@bvdm/delano`
-- binary name `delano`
-- embedded install assets instead of a GitHub-fetch wrapper
-- wrapper commands for `install`, `init`, `validate`, `status`, and `next`
+If you bootstrap with one-shot `npx`, keep using `npx` for wrapper commands:
 
-Local development examples from this repository:
+```bash
+npx -y @bvdm/delano@latest validate
+npx -y @bvdm/delano@latest status
+npx -y @bvdm/delano@latest next -- --all
+```
+
+If the package is installed locally or globally, run these inside the target repository:
 
 ```bash
-# Build the packaged asset payload
-npm run build:assets
+delano validate
+delano status
+delano next -- --all
+delano init <slug> "<Project Name>" <owner> <lead>
+```
 
-# Inspect the CLI surface
-node bin/delano.js --help
+The wrapper commands call the existing PM scripts under `.agents/scripts/pm/`. You can also run those scripts directly:
 
-# Install the approved base payload into another repo or scratch target
-node bin/delano.js install --target /path/to/repo --yes
+```bash
+bash .agents/scripts/pm/validate.sh
+bash .agents/scripts/pm/status.sh
+bash .agents/scripts/pm/next.sh --all
 ```
 
-### Daily operating loop
+## Required dependencies
 
-1. Keep project intent and execution synced in `.project/projects/<slug>/`.
-2. Execute work through workstreams and atomic tasks (`tasks/T-xxx.md`).
-3. Record progress/blockers in `updates/*.md`.
-4. Re-run validation before merge/handoff:
-   ```bash
-   bash .agents/scripts/pm/validate.sh
-   ```
+Delano v1.1 assumes these tools are available:
 
-### Install Delano into another repository
+- `node` 18 or newer
+- `bash`
+- `git`
+- `python3` or compatible `python` / `py`
 
-Preferred v1 path:
+The CLI does not bundle its own shell or Python runtime.
 
-```bash
-delano install --target /path/to/repo --yes
-```
+## Install behavior
 
-Current source-repo development path:
+`delano install` is conflict-first by default:
 
-```bash
-node bin/delano.js install --target /path/to/repo --yes
-```
+- it computes the full install plan before writing files
+- it aborts if an approved target path already exists
+- it reports each conflict as file, directory, or symlink
+- it only overwrites approved allowlist paths when `--force` is used
+- it does not touch unrelated files outside the allowlist
 
-Base install behavior:
-- installs only the approved allowlist payload
-- aborts on existing-path conflicts unless `--force` is used
-- does not install `AGENTS.md`, `CLAUDE.md`, `CODEX.md`, `OPENCODE.md`, or `PI.md` by default
+The base install payload intentionally excludes top-level adapter entry docs such as `AGENTS.md`, `CLAUDE.md`, `CODEX.md`, `OPENCODE.md`, and `PI.md`. Those remain opt-in only.
 
-Legacy bridge path:
+## v1.1 boundaries
 
-```bash
-./install-delano.sh
-```
+This package is deliberately narrow:
 
-The shell installer remains available for migration, but it is broader than the npm base install path and should be treated as the compatibility bridge rather than the preferred v1 behavior.
+- npm is the distribution surface
+- `.project` remains repo-owned after install
+- `.agents` remains the runtime surface
+- wrapper commands stay thin in v1.1
+- `install-delano.sh` remains available as the legacy bridge installer
 
-Legacy non-interactive example:
+## Local development
+
+From this repository:
 
 ```bash
-./install-delano.sh --target /path/to/repo --agents claude,codex --yes
+npm run build:assets
+node bin/delano.js --help
+node bin/delano.js --yes --target ./tmp/cli-install-smoke
 ```
 
-### Read next
+## Read next
 
-- `docs/user-guide.md` for the user-facing overview
-- `HANDBOOK.md` for full operating semantics
-- `.agents/scripts/README.md` for runtime script inventory
-- `AGENTS.md` and adapter entrypoints (`CLAUDE.md`, `CODEX.md`, etc.) for agent-specific bootstraps
+- `docs/user-guide.md` for the practical user flow
+- `HANDBOOK.md` for the full operating model
+- `.agents/scripts/README.md` for the runtime script inventory
+- `AGENTS.md` for adapter-neutral instructions

package/assets/payload/__dot_gitignore__

@@ -0,0 +1,20 @@
+# Runtime local artifacts
+.claude/logs/*.jsonl
+.claude/logs/tests/
+.agents/logs/*.jsonl
+.agents/logs/tests/
+
+# Keep structural markers and docs
+!.claude/logs/.gitkeep
+!.claude/logs/schema.md
+!.agents/logs/.gitkeep
+!.agents/logs/schema.md
+
+# Local Claude overrides
+.claude/settings.local.json
+.agents/settings.local.json
+
+# Node/npm local artifacts
+node_modules/
+assets/payload/
+*.tgz

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bvdm/delano",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Thin npm CLI for the Delano delivery runtime.",
   "license": "UNLICENSED",
   "bin": {

package/src/cli/commands/install.js

@@ -12,6 +12,7 @@ function getInstallHelp() {
   return [
     "Usage:",
     "  delano install [options]",
+    "  delano [options]",
     "",
     "Options:",
     "  --target <dir>     Install into the given directory. Defaults to the current working directory.",
@@ -23,7 +24,12 @@ function getInstallHelp() {
     "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."
+    "  - Only installs the approved base payload; top-level adapter entry docs remain opt-in and are not installed in v1.",
+    "",
+    "Examples:",
+    "  delano install --target ../repo --yes",
+    "  delano --yes",
+    "  npx -y @bvdm/delano@latest --yes"
   ].join("\n");
 }
 

package/src/cli/index.js

@@ -25,6 +25,51 @@ const commands = {
   next: wrapperCommands.next
 };
 
+function isInstallShorthand(argv) {
+  if (argv.length === 0) {
+    return false;
+  }
+
+  return argv[0].startsWith("-");
+}
+
+function resolveInvocation(argv) {
+  if (argv.length === 0) {
+    return { kind: "help" };
+  }
+
+  const [commandName, ...commandArgs] = argv;
+
+  if (commandName === "-h" || commandName === "--help" || commandName === "help") {
+    return { kind: "help" };
+  }
+
+  if (commandName === "-v" || commandName === "--version" || commandName === "version") {
+    return { kind: "version" };
+  }
+
+  if (isInstallShorthand(argv)) {
+    return {
+      kind: "command",
+      commandName: "install",
+      commandArgs: argv,
+      command: commands.install
+    };
+  }
+
+  const command = commands[commandName];
+  if (!command) {
+    throw new CliError(`Unknown command: ${commandName}\n\n${getGeneralHelp()}`, 1);
+  }
+
+  return {
+    kind: "command",
+    commandName,
+    commandArgs,
+    command
+  };
+}
+
 function getPackageVersion() {
   const packageJsonPath = path.join(getPackageRoot(), "package.json");
   const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8"));
@@ -50,36 +95,33 @@ function getGeneralHelp() {
     "  -v, --version   Show version",
     "",
     "Examples:",
-    "  delano install --target ../my-repo --yes",
+    "  delano --yes",
+    "  delano --target ../my-repo --yes",
+    "  npx -y @bvdm/delano@latest --yes",
     "  delano validate",
     "  delano next -- --all",
     "",
+    "Shorthand:",
+    "  delano [install-options] is equivalent to delano install [install-options].",
+    "",
     "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;
+  const invocation = resolveInvocation(argv);
 
-  if (commandName === "-h" || commandName === "--help" || commandName === "help") {
+  if (invocation.kind === "help") {
     console.log(getGeneralHelp());
     return 0;
   }
 
-  if (commandName === "-v" || commandName === "--version" || commandName === "version") {
+  if (invocation.kind === "version") {
     console.log(getPackageVersion());
     return 0;
   }
 
-  const command = commands[commandName];
-  if (!command) {
-    throw new CliError(`Unknown command: ${commandName}\n\n${getGeneralHelp()}`, 1);
-  }
+  const { command, commandArgs } = invocation;
 
   if (commandArgs.includes("--help") || commandArgs.includes("-h")) {
     const helpText = typeof command.help === "function" ? command.help() : getGeneralHelp();
@@ -93,5 +135,6 @@ async function run(argv) {
 module.exports = {
   commands,
   getGeneralHelp,
+  resolveInvocation,
   run
 };

package/src/cli/lib/asset-paths.js

@@ -0,0 +1,21 @@
+const path = require("node:path");
+
+const PACKAGED_BASENAME_MAP = new Map([
+  [".gitignore", "__dot_gitignore__"]
+]);
+
+function getPackagedAssetRelativePath(relativePath) {
+  const normalizedPath = relativePath.split(/[\\/]/).join("/");
+  const parsedPath = path.posix.parse(normalizedPath);
+  const packagedBasename = PACKAGED_BASENAME_MAP.get(parsedPath.base);
+
+  if (!packagedBasename) {
+    return normalizedPath;
+  }
+
+  return parsedPath.dir ? `${parsedPath.dir}/${packagedBasename}` : packagedBasename;
+}
+
+module.exports = {
+  getPackagedAssetRelativePath
+};

package/src/cli/lib/install.js

@@ -11,11 +11,20 @@ const path = require("node:path");
 const readline = require("node:readline/promises");
 const { stdin, stdout } = require("node:process");
 
+const { getPackagedAssetRelativePath } = require("./asset-paths");
 const { CliError } = require("./errors");
 const { getPackageRoot, getPathType } = require("./runtime");
 
 const SUPPORTED_AGENTS = ["claude", "codex", "opencode", "pi"];
 
+function getMissingPackagedAssetMessage(relativePath) {
+  return [
+    `Packaged asset missing for '${relativePath}'.`,
+    "If you are running from a source checkout, run 'npm run build:assets' first.",
+    "If you installed the published npm package, the package is incomplete and needs to be rebuilt and republished."
+  ].join(" ");
+}
+
 function readInstallManifest() {
   const manifestPath = path.join(getPackageRoot(), "assets", "install-manifest.json");
   const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
@@ -114,12 +123,9 @@ function parseInstallArgs(args) {
 function buildInstallPlan(options) {
   const { manifest, payloadRoot } = readInstallManifest();
   const items = manifest.paths.map((relativePath) => {
-    const sourcePath = path.join(payloadRoot, relativePath);
+    const sourcePath = path.join(payloadRoot, getPackagedAssetRelativePath(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
-      );
+      throw new CliError(getMissingPackagedAssetMessage(relativePath), 1);
     }
 
     return {
@@ -257,5 +263,6 @@ module.exports = {
   parseInstallArgs,
   printConflicts,
   printPlanSummary,
-  readInstallManifest
+  readInstallManifest,
+  getMissingPackagedAssetMessage
 };

package/src/cli/lib/runtime.js

@@ -50,6 +50,11 @@ function resolveBash() {
   }
 
   if (process.platform === "win32") {
+    candidates.push(
+      "C:\\Program Files\\Git\\bin\\bash.exe",
+      "C:\\Program Files\\Git\\usr\\bin\\bash.exe"
+    );
+
     const whereResult = spawnSync("where.exe", ["bash"], {
       encoding: "utf8",
       stdio: ["ignore", "pipe", "ignore"]
@@ -62,11 +67,6 @@ function resolveBash() {
         }
       }
     }
-
-    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",
@@ -90,9 +90,18 @@ function resolveBash() {
   );
 }
 
+function normalizeBashScriptPath(scriptPath) {
+  if (process.platform !== "win32") {
+    return scriptPath;
+  }
+
+  return scriptPath.replace(/\\/g, "/");
+}
+
 function runBashScript(scriptPath, args, options = {}) {
   const bashPath = resolveBash();
-  const result = spawnSync(bashPath, [scriptPath, ...args], {
+  const normalizedScriptPath = normalizeBashScriptPath(scriptPath);
+  const result = spawnSync(bashPath, [normalizedScriptPath, ...args], {
     cwd: options.cwd || process.cwd(),
     stdio: "inherit",
     env: options.env || process.env
@@ -117,6 +126,7 @@ module.exports = {
   findDelanoRoot,
   getPackageRoot,
   getPathType,
+  normalizeBashScriptPath,
   resolveBash,
   runBashScript
 };