@bvdm/delano 0.2.3 → 0.2.4

package/assets/payload/.delano/viewer/server.js

@@ -12,7 +12,16 @@ const { spawn, spawnSync } = require('node:child_process');
 const repoRoot = path.resolve(process.env.DELANO_VIEWER_ROOT || path.resolve(__dirname, '..', '..'));
 const projectRoot = path.join(repoRoot, '.project');
 const publicRoot = path.join(__dirname, 'public');
-const port = Number(process.env.DELANO_VIEWER_PORT || process.env.PORT || 3977);
+const DEFAULT_PORT = 3977;
+const MAX_PORT = 65535;
+const MAX_PORT_ATTEMPTS = 100;
+const startPort = normalizePort(process.env.DELANO_VIEWER_PORT || process.env.PORT, DEFAULT_PORT);
+
+function normalizePort(value, fallback) {
+  const parsed = Number(value || fallback);
+  if (!Number.isInteger(parsed) || parsed < 1 || parsed > MAX_PORT) return fallback;
+  return parsed;
+}
 
 function isInside(parent, child) {
   const rel = path.relative(parent, child);
@@ -332,6 +341,7 @@ function sendStatic(res, pathname) {
   const ext = path.extname(resolved).toLowerCase();
   const mimeMap = {
     '.js': 'text/javascript',
+    '.jsx': 'text/javascript',
     '.css': 'text/css',
     '.svg': 'image/svg+xml',
     '.png': 'image/png',
@@ -340,7 +350,7 @@ function sendStatic(res, pathname) {
     '.webp': 'image/webp',
     '.ico': 'image/x-icon',
   };
-  const isText = ext === '.js' || ext === '.css' || ext === '.svg' || ext === '' || ext === '.html';
+  const isText = ext === '.js' || ext === '.jsx' || ext === '.css' || ext === '.svg' || ext === '' || ext === '.html';
   const type = mimeMap[ext] || 'text/html';
   const headers = isText ? { 'content-type': `${type}; charset=utf-8` } : { 'content-type': type };
   res.writeHead(200, headers);
@@ -384,6 +394,37 @@ const server = http.createServer((req, res) => {
   }
 });
 
-server.listen(port, '127.0.0.1', () => {
-  console.log(`Delano read-only viewer: http://127.0.0.1:${port}`);
-});
+function listenWithPortFallback(server, firstPort, host = '127.0.0.1') {
+  let port = firstPort;
+  let attempts = 0;
+
+  const listen = () => {
+    server.once('error', onError);
+    server.listen(port, host);
+  };
+
+  const onError = (error) => {
+    if (error.code === 'EADDRINUSE' && port < MAX_PORT && attempts < MAX_PORT_ATTEMPTS) {
+      attempts += 1;
+      port += 1;
+      listen();
+      return;
+    }
+
+    console.error(`Failed to start Delano viewer on ${host}:${port}: ${error.message}`);
+    process.exitCode = 1;
+  };
+
+  const onListening = () => {
+    server.removeListener('error', onError);
+    const address = server.address();
+    const actualPort = typeof address === 'object' && address ? address.port : port;
+    const skipped = actualPort !== firstPort ? ` (${firstPort} was unavailable)` : '';
+    console.log(`Delano read-only viewer: http://${host}:${actualPort}${skipped}`);
+  };
+
+  server.on('listening', onListening);
+  listen();
+}
+
+listenWithPortFallback(server, startPort);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bvdm/delano",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "CLI for the Delano delivery runtime.",
   "license": "MIT",
   "repository": {

package/src/cli/commands/install.js

@@ -30,7 +30,7 @@ function getInstallHelp() {
     "  -h, --help         Show command help.",
     "",
     "Categories:",
-    "  agent-runtime, skills, viewer, project-context, project-templates,",
+    "  agent-runtime, codex-hooks, skills, viewer, project-context, project-templates,",
     "  project-registry, project-projects, handbook, legacy-installer",
     "",
     "Behavior:",
@@ -38,6 +38,7 @@ function getInstallHelp() {
     "  - Aborts on conflicts by default.",
     "  - Filters the plan before conflict detection when --only or --exclude is used.",
     "  - Treats .project/context, .project/projects, and .project/registry as repo-owned state after install.",
+    "  - Merges .codex/hooks.json when it exists; invalid or non-file hook configs are skipped without blocking install.",
     "  - Only installs the approved base payload; top-level adapter entry docs remain opt-in and are not installed in v1.",
     "",
     "Examples:",

package/src/cli/commands/viewer.js

@@ -43,7 +43,8 @@ function getViewerHelp() {
     "  -h, --help       Show help",
     "",
     "Environment:",
-    "  DELANO_VIEWER_PORT or PORT overrides the default port 3977."
+    "  DELANO_VIEWER_PORT or PORT sets the starting port, defaulting to 3977.",
+    "  If that port is busy, the viewer starts on the next available port."
   ].join("\n");
 }
 

package/src/cli/commands/wrapper.js

@@ -8,7 +8,7 @@ function createWrapperCommand(scriptName) {
       return runPmScript(scriptName, passthrough);
     },
     help() {
-      return [
+      const lines = [
         "Usage:",
         `  delano ${scriptName} [-- <script-args>]`,
         "",
@@ -16,7 +16,18 @@ 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");
     }
   };
 }

package/src/cli/index.js

@@ -116,6 +116,7 @@ function getGeneralHelp() {
     "  npx -y @bvdm/delano@latest --yes",
     "  delano viewer",
     "  delano validate",
+    "  delano status --open --brief",
     "  delano next -- --all",
     "",
     "Shorthand:",

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
 };