@dalzoubi/dev-agents-sync 2.0.16 → 2.0.17

package/src/steering.mjs

@@ -0,0 +1,117 @@
+/**
+ * Steering scaffold seeding.
+ *
+ * Steering files (`steering/decisions.md`, `glossary.md`, `architecture.md`) are
+ * a persistent, CONSUMER-OWNED memory layer. Agents read all three at session
+ * start and append to them; the toolkit seeds blank scaffolds ONCE and then never
+ * rewrites them.
+ *
+ * Invariants enforced here:
+ *   - Seed-if-absent: a file is written only when it does not already exist. An
+ *     existing file (edited by the consumer or a prior session) is left
+ *     byte-identical — never overwritten.
+ *   - No marker: seeded files carry NO `managed-by` marker, so they are
+ *     consumer-owned and the lockfile never tracks them.
+ *   - Atomic: a write failure surfaces a stable `ESTEER_WRITE` code and never
+ *     leaves a half-written scaffold (each file is written whole or not at all).
+ *   - --dry-run writes nothing.
+ *
+ * The scaffold bodies are inlined (not read from disk) so the published CLI is
+ * self-contained and does not depend on the canonical `.agents/steering/` tree
+ * at runtime. They are deliberately blank/minimal — a heading plus a one-line
+ * "what goes here" comment — and carry no marker and no consumer-specific
+ * language.
+ */
+
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+
+/** The three steering scaffold files and their blank/minimal seed bodies. */
+export const STEERING_SCAFFOLDS = {
+  'decisions.md':
+    '# Decisions\n\n' +
+    '<!-- What goes here: durable, dated decisions and their rationale, one line each ' +
+    '(YYYY-MM-DD — <decision>: <why>). Consumer-owned; agents append, never rewrite. -->\n',
+  'glossary.md':
+    '# Glossary\n\n' +
+    '<!-- What goes here: project-specific terms and their definitions, one entry each. ' +
+    'Consumer-owned; keep it the shared vocabulary every agent reads. -->\n',
+  'architecture.md':
+    '# Architecture\n\n' +
+    '<!-- What goes here: load-bearing architecture notes, core patterns, and constraints ' +
+    'agents should respect. Consumer-owned; keep it current. -->\n',
+};
+
+class SteeringWriteError extends Error {
+  constructor(message, { exitCode = 2, cause } = {}) {
+    super(message);
+    this.name = 'SteeringWriteError';
+    this.code = 'ESTEER_WRITE';
+    this.exitCode = exitCode;
+    if (cause) this.cause = cause;
+  }
+}
+
+/**
+ * Seeds the steering scaffold into <consumerCwd>/.claude/steering/, writing
+ * each scaffold file only when it is absent.
+ *
+ * @param {string} consumerCwd
+ * @param {{ dryRun?: boolean }} [opts]
+ * @returns {{ seeded: string[], present: string[], dryRun: boolean }}
+ *   seeded  — relative paths (steering/<name>) that were (or would be) written.
+ *   present — relative paths left untouched because they already existed.
+ */
+export function seedSteering(consumerCwd, opts = {}) {
+  const { dryRun = false } = opts;
+  const steeringDir = path.join(consumerCwd, '.claude', 'steering');
+
+  const seeded = [];
+  const present = [];
+
+  // First pass: decide what to write without touching the filesystem, so a
+  // dry-run is read-only and a real run knows the full plan up front.
+  const toWrite = [];
+  for (const [filename, content] of Object.entries(STEERING_SCAFFOLDS)) {
+    const absPath = path.join(steeringDir, filename);
+    const rel = `steering/${filename}`;
+    if (existsSync(absPath)) {
+      present.push(rel);
+    } else {
+      toWrite.push({ absPath, content, rel });
+    }
+  }
+
+  if (dryRun) {
+    for (const w of toWrite) seeded.push(w.rel);
+    return { seeded, present, dryRun: true };
+  }
+
+  // Write whole files only. A failure surfaces ESTEER_WRITE; because each file
+  // is written in a single writeFileSync, a failure never leaves a file
+  // half-written (the OS write is the unit of atomicity we rely on here).
+  try {
+    if (toWrite.length > 0) {
+      mkdirSync(steeringDir, { recursive: true });
+    }
+    for (const w of toWrite) {
+      writeFileSync(w.absPath, w.content, 'utf8');
+      seeded.push(w.rel);
+    }
+  } catch (err) {
+    throw new SteeringWriteError(
+      `ESTEER_WRITE: could not write ${path.join('.claude', 'steering')} — check directory permissions`,
+      { cause: err },
+    );
+  }
+
+  return { seeded, present, dryRun: false };
+}
+
+/** Human-readable summary line consistent with the existing CLI output style. */
+export function steeringSummary(result) {
+  if (result.seeded.length > 0) {
+    return `steering/ seeded (${result.seeded.length} file${result.seeded.length === 1 ? '' : 's'})`;
+  }
+  return 'steering/ present — left untouched';
+}

package/src/writer.mjs

@@ -8,10 +8,22 @@
  * Rejects path traversal (`..`).
  */
 
-import { mkdirSync, writeFileSync, existsSync, readFileSync } from 'node:fs';
+import { mkdirSync, writeFileSync, existsSync, readFileSync, chmodSync } from 'node:fs';
 import path from 'node:path';
 import { hasMarker, hasMarkerOnFirstLine } from './marker.mjs';
 
+/**
+ * Managed hook scripts (`.claude/hooks/*.sh`) must be executable so Claude Code
+ * can run them. Other managed files are plain content and keep default perms.
+ */
+function isExecutableHookKey(relKey) {
+  return (
+    typeof relKey === 'string' &&
+    /(^|\/)hooks\//.test(relKey.replace(/\\/g, '/')) &&
+    relKey.endsWith('.sh')
+  );
+}
+
 const TARGET_PREFIX = {
   claude: '.claude',
   cursor: '.cursor',
@@ -144,6 +156,12 @@ export function writeManagedFile({ absPath, relKey, content, force }) {
   }
   mkdirSync(path.dirname(absPath), { recursive: true });
   writeFileSync(absPath, content, 'utf8');
+  // Hook scripts are executables — set the exec bit deterministically (0o755)
+  // so they are runnable immediately after install. chmod is a no-op on
+  // platforms without POSIX permissions, so this is safe everywhere.
+  if (isExecutableHookKey(relKey)) {
+    chmodSync(absPath, 0o755);
+  }
 }
 
 /** Returns true if the path under <root>/.claude or <root>/.cursor exists with content matching `expected`. */