durable-context 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ricardo Mendez Rodriguez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,24 @@
+# durable-context
+
+Invocation-only skills and scaffold for durable planning in the repo.
+
+Install into a project:
+
+```bash
+npx durable-context init --project-name "My App"
+```
+
+Adds `context/`, `decisions/`, and skills `plan-with-context` and `dive-into-plan`.
+
+## Use
+
+```text
+Plan with durable context: <what you want to build>
+Dive into the plan.
+```
+
+Skills are invocation-only — they do not run automatically.
+
+Options: `--target`, `--dry-run`, `--force`, `status`.
+
+For release-anchored documentation, see the `reference-docs` package.

package/bin/durable-context.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { runCli, reportError } from '../lib/installer.js';
+
+const cliName = 'durable-context';
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const packageJson = JSON.parse(await readFile(path.join(packageRoot, 'package.json'), 'utf8'));
+
+const agentsStart = '<!-- durable-context:start -->';
+const agentsEnd = '<!-- durable-context:end -->';
+
+const skills = [
+  {
+    name: 'plan-with-context',
+    readmeEntry:
+      '- `plan-with-context` - invoke explicitly to draft a durable plan in an initiative `plan.md`.'
+  },
+  {
+    name: 'dive-into-plan',
+    readmeEntry:
+      '- `dive-into-plan` - invoke explicitly to interrogate a settled plan, distribute it into initiative docs, and promote decisions.'
+  }
+];
+
+function renderAgentSection(projectName) {
+  return `${agentsStart}
+## Durable Context
+
+Working context under [\`context/\`](context/); durable decisions under [\`decisions/\`](decisions/).
+Initiatives under [\`context/initiatives/\`](context/initiatives/) are disposable; promote accepted decisions to [\`decisions/\`](decisions/).
+
+Invocation-only skills — ask by name:
+
+- [\`.agents/skills/plan-with-context/SKILL.md\`](.agents/skills/plan-with-context/SKILL.md) — draft a plan in \`plan.md\`.
+- [\`.agents/skills/dive-into-plan/SKILL.md\`](.agents/skills/dive-into-plan/SKILL.md) — interrogate gaps, distribute into per-concern docs, promote to [\`decisions/\`](decisions/).
+
+[\`context/project-profile.md\`](context/project-profile.md) — repo-wide stack, commands, and test facts when populated.
+${agentsEnd}`;
+}
+
+const config = {
+  cliName,
+  packageRoot,
+  packageJson,
+  summaryLabel: 'Durable Context',
+  metadataPath: '.durable-context/install.json',
+  skills,
+  agents: {
+    start: agentsStart,
+    end: agentsEnd,
+    render: renderAgentSection
+  },
+  nextSteps: [
+    'Then: invoke .agents/skills/plan-with-context/SKILL.md when you start planning an initiative.'
+  ]
+};
+
+runCli(config, process.argv.slice(2)).catch((error) => reportError(error, cliName));

package/lib/installer.js

@@ -0,0 +1,553 @@
+import { execPath } from 'node:process';
+import { constants as fsConstants } from 'node:fs';
+import { access, mkdir, readFile, readdir, rm, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+const agentsSkillsRelative = '.agents/skills';
+
+/**
+ * Generic installer shared by durable-context and reference-docs packages.
+ *
+ * Each package supplies a `config` describing its payload:
+ *   - cliName:        bin name, used in help and error text
+ *   - packageRoot:    absolute path to the package directory
+ *   - packageJson:    parsed package.json of the package
+ *   - skills:         [{ name, readmeEntry }] copied into .agents/skills
+ *   - agents:         { start, end, render(projectName) } AGENTS.md section
+ *   - metadataPath:   relative path of the install metadata file in the target
+ *   - nextSteps:      strings printed after a successful install
+ *   - summaryLabel:   short label used in the final summary line
+ */
+export async function runCli(config, argv) {
+  const args = parseArgs(argv, config);
+
+  if (args.help) {
+    printHelp(config);
+    return;
+  }
+
+  if (args.version) {
+    console.log(config.packageJson.version);
+    return;
+  }
+
+  if (args.command === 'status') {
+    await printStatus(config, args.target);
+    return;
+  }
+
+  if (args.command !== 'init') {
+    throw new Error(`Unknown command "${args.command}". Run "${config.cliName} --help".`);
+  }
+
+  const targetRoot = path.resolve(args.target);
+  const projectName = args.projectName ?? (await inferProjectName(targetRoot));
+  const installer = new Installer({
+    config,
+    targetRoot,
+    projectName,
+    force: args.force,
+    dryRun: args.dryRun
+  });
+
+  await installer.init();
+}
+
+function parseArgs(argv, config) {
+  const options = {
+    command: 'help',
+    target: process.cwd(),
+    projectName: undefined,
+    force: false,
+    dryRun: false,
+    help: false,
+    version: false
+  };
+
+  const positionals = [];
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+
+    if (arg === '--help' || arg === '-h') {
+      options.help = true;
+      continue;
+    }
+
+    if (arg === '--version' || arg === '-v') {
+      options.version = true;
+      continue;
+    }
+
+    if (arg === '--force') {
+      options.force = true;
+      continue;
+    }
+
+    if (arg === '--dry-run') {
+      options.dryRun = true;
+      continue;
+    }
+
+    if (arg.startsWith('--target=')) {
+      options.target = arg.slice('--target='.length);
+      continue;
+    }
+
+    if (arg === '--target') {
+      options.target = readOptionValue(argv, index, '--target');
+      index += 1;
+      continue;
+    }
+
+    if (arg.startsWith('--project-name=')) {
+      options.projectName = arg.slice('--project-name='.length);
+      continue;
+    }
+
+    if (arg === '--project-name') {
+      options.projectName = readOptionValue(argv, index, '--project-name');
+      index += 1;
+      continue;
+    }
+
+    if (arg.startsWith('-')) {
+      throw new Error(`Unknown option "${arg}". Run "${config.cliName} --help".`);
+    }
+
+    positionals.push(arg);
+  }
+
+  if (positionals.length > 1) {
+    throw new Error(`Unexpected arguments: ${positionals.slice(1).join(' ')}`);
+  }
+
+  options.command = positionals[0] ?? (options.help || options.version ? 'meta' : 'help');
+  options.help = options.help || options.command === 'help';
+
+  return options;
+}
+
+function readOptionValue(argv, index, optionName) {
+  const value = argv[index + 1];
+
+  if (!value || value.startsWith('-')) {
+    throw new Error(`${optionName} requires a value.`);
+  }
+
+  return value;
+}
+
+function printHelp(config) {
+  console.log(`${config.cliName}
+
+Usage:
+  ${config.cliName} init [options]
+  ${config.cliName} status [options]
+
+Options:
+  --target <path>          Project root to install into. Defaults to cwd.
+  --project-name <name>    Name used to replace PROJECT_NAME placeholders.
+  --force                  Replace existing generated directories.
+  --dry-run                Show planned changes without writing files.
+  -h, --help               Show help.
+  -v, --version            Show package version.
+
+Examples:
+  npx ${config.packageJson.name} init --project-name "My App"
+  npx ${config.packageJson.name}@${config.packageJson.version} init --project-name "My App"
+  npx ${config.packageJson.name} status --target ../existing-project
+
+The status command reads ${config.metadataPath} from an initialized project.
+`);
+}
+
+async function inferProjectName(targetRoot) {
+  try {
+    const packageJson = JSON.parse(await readFile(path.join(targetRoot, 'package.json'), 'utf8'));
+
+    if (typeof packageJson.name === 'string' && packageJson.name.trim()) {
+      return packageJson.name.replace(/^@[^/]+\//, '');
+    }
+  } catch {
+    // Fall through to the directory name.
+  }
+
+  return path.basename(targetRoot);
+}
+
+class Installer {
+  constructor({ config, targetRoot, projectName, force, dryRun }) {
+    this.config = config;
+    this.templateDir = path.join(config.packageRoot, 'template');
+    this.targetRoot = targetRoot;
+    this.projectName = projectName;
+    this.force = force;
+    this.dryRun = dryRun;
+    this.actions = [];
+    this.agentsFilePath = path.join(targetRoot, 'AGENTS.md');
+  }
+
+  async init() {
+    await this.ensureDirectory(this.targetRoot);
+
+    await this.installAgentsFile();
+    await this.installSkills();
+    await this.installPayloadRoots();
+    await this.writeMetadata();
+
+    this.printSummary();
+  }
+
+  async installPayloadRoots() {
+    const entries = await readdir(this.templateDir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      if (entry.name === 'AGENTS.md' || entry.name === '.agents' || entry.name === '.DS_Store') {
+        continue;
+      }
+
+      await this.copyTemplatePath(entry.name, entry.name);
+    }
+  }
+
+  async installAgentsFile() {
+    const targetFile = await this.findAgentsFile();
+    const targetDisplay = path.basename(targetFile);
+    this.agentsFilePath = targetFile;
+
+    const section = this.config.agents.render(this.projectName);
+    const { start, end } = this.config.agents;
+
+    if (!(await exists(targetFile))) {
+      const templateAgents = path.join(this.templateDir, 'AGENTS.md');
+
+      if (await exists(templateAgents)) {
+        const text = (await readFile(templateAgents, 'utf8')).replaceAll('PROJECT_NAME', this.projectName);
+        await this.writeFile(path.join(this.targetRoot, 'AGENTS.md'), text, 'create AGENTS.md');
+        this.agentsFilePath = path.join(this.targetRoot, 'AGENTS.md');
+        return;
+      }
+
+      await this.writeFile(path.join(this.targetRoot, 'AGENTS.md'), `${section}\n`, 'create AGENTS.md');
+      this.agentsFilePath = path.join(this.targetRoot, 'AGENTS.md');
+      return;
+    }
+
+    const current = await readFile(targetFile, 'utf8');
+
+    if (current.includes(start) && current.includes(end)) {
+      const updated = current.replace(
+        new RegExp(`${escapeRegExp(start)}[\\s\\S]*?${escapeRegExp(end)}`),
+        section
+      );
+
+      if (updated === current) {
+        this.note(`${targetDisplay} already has the ${this.config.summaryLabel} guidance`);
+        return;
+      }
+
+      await this.writeFile(targetFile, updated, `update ${targetDisplay} ${this.config.summaryLabel} section`);
+      return;
+    }
+
+    const separator = current.endsWith('\n') ? '\n' : '\n\n';
+    await this.writeFile(
+      targetFile,
+      `${current}${separator}${section}\n`,
+      `append ${this.config.summaryLabel} guidance to ${targetDisplay}`
+    );
+  }
+
+  async findAgentsFile() {
+    const canonicalPath = path.join(this.targetRoot, 'AGENTS.md');
+
+    let entries;
+
+    try {
+      entries = await readdir(this.targetRoot, { withFileTypes: true });
+    } catch {
+      return canonicalPath;
+    }
+
+    if (entries.some((entry) => entry.isFile() && entry.name === 'AGENTS.md')) {
+      return canonicalPath;
+    }
+
+    const match = entries
+      .filter((entry) => entry.isFile() && entry.name.toLowerCase() === 'agents.md')
+      .map((entry) => entry.name)
+      .sort((left, right) => left.localeCompare(right))[0];
+
+    return match ? path.join(this.targetRoot, match) : canonicalPath;
+  }
+
+  async installSkills() {
+    for (const skill of this.config.skills) {
+      await this.copyTemplatePath(
+        `${agentsSkillsRelative}/${skill.name}`,
+        `${agentsSkillsRelative}/${skill.name}`
+      );
+    }
+
+    const readmeTarget = await this.findExistingTargetPath(`${agentsSkillsRelative}/README.md`);
+    const readmePath = readmeTarget.exists
+      ? readmeTarget.path
+      : path.join(this.targetRoot, `${agentsSkillsRelative}/README.md`);
+    const readmeDisplay = readmeTarget.exists ? readmeTarget.display : `${agentsSkillsRelative}/README.md`;
+
+    if (!(await exists(readmePath))) {
+      await this.copyTemplatePath(`${agentsSkillsRelative}/README.md`, `${agentsSkillsRelative}/README.md`);
+      return;
+    }
+
+    const current = await readFile(readmePath, 'utf8');
+    const missingSkills = this.config.skills.filter((skill) => !current.includes(skill.name));
+
+    if (missingSkills.length === 0) {
+      this.note(`${readmeDisplay} already lists the ${this.config.summaryLabel} skills`);
+      return;
+    }
+
+    const entry = [
+      '',
+      `## ${this.config.summaryLabel} Skills`,
+      '',
+      ...missingSkills.map((skill) => skill.readmeEntry),
+      ''
+    ].join('\n');
+
+    await this.writeFile(
+      readmePath,
+      `${current.trimEnd()}\n${entry}`,
+      `append ${this.config.summaryLabel} skills to ${readmeDisplay}`
+    );
+  }
+
+  async copyTemplatePath(sourceRelative, targetRelative) {
+    const sourcePath = path.join(this.templateDir, sourceRelative);
+    const targetInfo = await this.findExistingTargetPath(targetRelative);
+
+    if (!(await exists(sourcePath))) {
+      return false;
+    }
+
+    const targetPath = path.join(this.targetRoot, targetRelative);
+
+    if (targetInfo.exists) {
+      const variantNote = targetInfo.caseVariant ? ` at ${targetInfo.display}` : '';
+
+      if (!this.force) {
+        this.note(`skip ${targetRelative} (already exists${variantNote}; use --force to replace)`);
+        return false;
+      }
+
+      await this.removePath(targetInfo.path, `replace ${targetInfo.display}`);
+    }
+
+    await this.copyRecursive(sourcePath, targetPath, targetRelative);
+    return true;
+  }
+
+  async findExistingTargetPath(targetRelative) {
+    const parts = targetRelative.split('/').filter(Boolean);
+    let currentPath = this.targetRoot;
+    const displayParts = [];
+
+    for (const part of parts) {
+      let entries;
+
+      try {
+        entries = await readdir(currentPath, { withFileTypes: true });
+      } catch {
+        return this.missingTargetPath(targetRelative);
+      }
+
+      const exactMatch = entries.find((entry) => entry.name === part);
+      const caseMatch = exactMatch ?? entries.find((entry) => entry.name.toLowerCase() === part.toLowerCase());
+
+      if (!caseMatch) {
+        return this.missingTargetPath(targetRelative);
+      }
+
+      currentPath = path.join(currentPath, caseMatch.name);
+      displayParts.push(caseMatch.name);
+    }
+
+    const display = displayParts.join('/');
+
+    return {
+      caseVariant: display !== targetRelative,
+      display,
+      exists: true,
+      path: currentPath
+    };
+  }
+
+  missingTargetPath(targetRelative) {
+    return {
+      caseVariant: false,
+      display: targetRelative,
+      exists: false,
+      path: path.join(this.targetRoot, targetRelative)
+    };
+  }
+
+  async copyRecursive(sourcePath, targetPath, displayPath) {
+    const sourceStats = await stat(sourcePath);
+
+    if (sourceStats.isDirectory()) {
+      await this.ensureDirectory(targetPath, `create ${displayPath}/`);
+      const entries = await readdir(sourcePath, { withFileTypes: true });
+
+      for (const entry of entries) {
+        if (entry.name === '.DS_Store') {
+          continue;
+        }
+
+        await this.copyRecursive(
+          path.join(sourcePath, entry.name),
+          path.join(targetPath, entry.name),
+          path.posix.join(displayPath, entry.name)
+        );
+      }
+
+      return;
+    }
+
+    const contents = await readFile(sourcePath);
+    const transformed = this.transformText(contents);
+    await this.writeFile(targetPath, transformed, `create ${displayPath}`);
+  }
+
+  transformText(contents) {
+    return contents.toString('utf8').replaceAll('PROJECT_NAME', this.projectName);
+  }
+
+  async writeMetadata() {
+    const metadataPath = path.join(this.targetRoot, this.config.metadataPath);
+    const previous = await readOptionalJson(metadataPath);
+    const now = new Date().toISOString();
+    const metadata = {
+      schemaVersion: 1,
+      packageName: this.config.packageJson.name,
+      installedVersion: this.config.packageJson.version,
+      firstInstalledVersion:
+        previous?.firstInstalledVersion ?? previous?.installedVersion ?? this.config.packageJson.version,
+      firstInstalledAt: previous?.firstInstalledAt ?? previous?.installedAt ?? now,
+      lastUpdatedAt: now,
+      projectName: this.projectName,
+      installedSkills: this.config.skills.map((skill) => skill.name)
+    };
+
+    await this.writeFile(
+      metadataPath,
+      `${JSON.stringify(metadata, null, 2)}\n`,
+      `${previous ? 'update' : 'create'} ${this.config.metadataPath}`
+    );
+  }
+
+  async ensureDirectory(directory, message) {
+    if (message) {
+      this.note(message);
+    }
+
+    if (!this.dryRun) {
+      await mkdir(directory, { recursive: true });
+    }
+  }
+
+  async removePath(filePath, message) {
+    this.note(message);
+
+    if (!this.dryRun) {
+      await rm(filePath, { recursive: true, force: true });
+    }
+  }
+
+  async writeFile(filePath, contents, message) {
+    this.note(message);
+
+    if (!this.dryRun) {
+      await mkdir(path.dirname(filePath), { recursive: true });
+      await writeFile(filePath, contents);
+    }
+  }
+
+  note(message) {
+    this.actions.push(message);
+  }
+
+  printSummary() {
+    const prefix = this.dryRun ? '[dry-run] ' : '';
+
+    for (const action of this.actions) {
+      console.log(`${prefix}${action}`);
+    }
+
+    console.log(`${prefix}${this.config.summaryLabel} ready for ${this.projectName}.`);
+
+    if (!this.dryRun) {
+      console.log(`Next: ask your agent to read ${this.agentsFilePath}.`);
+
+      for (const step of this.config.nextSteps ?? []) {
+        console.log(step);
+      }
+    }
+  }
+}
+
+async function printStatus(config, target) {
+  const targetRoot = path.resolve(target);
+  const metadataPath = path.join(targetRoot, config.metadataPath);
+  const metadata = await readOptionalJson(metadataPath);
+
+  console.log(`${config.summaryLabel} status for ${targetRoot}`);
+  console.log(`Running CLI version: ${config.packageJson.version}`);
+
+  if (!metadata) {
+    console.log('Installed metadata: not found');
+    console.log(`Metadata path: ${config.metadataPath}`);
+    return;
+  }
+
+  console.log(`Installed version: ${metadata.installedVersion ?? 'Unknown'}`);
+  console.log(`Project: ${metadata.projectName ?? 'Unknown'}`);
+  console.log(`Installed skills: ${formatList(metadata.installedSkills)}`);
+  console.log(`Metadata path: ${config.metadataPath}`);
+
+  if (metadata.installedVersion && metadata.installedVersion !== config.packageJson.version) {
+    console.log('Note: running CLI version differs from installed metadata.');
+  }
+}
+
+function formatList(value) {
+  return Array.isArray(value) && value.length > 0 ? value.join(', ') : 'Unknown';
+}
+
+async function readOptionalJson(filePath) {
+  try {
+    return JSON.parse(await readFile(filePath, 'utf8'));
+  } catch {
+    return undefined;
+  }
+}
+
+async function exists(filePath) {
+  try {
+    await access(filePath, fsConstants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+export function reportError(error, cliName) {
+  console.error(error.message);
+  console.error(`Run "${path.basename(execPath)} ${cliName} --help" for usage.`);
+  process.exitCode = 1;
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "durable-context",
+  "version": "1.0.0",
+  "description": "Invocation-only skills and scaffold for durable planning: initiatives in context/, decisions in an append-only log.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "durable-context": "bin/durable-context.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "template/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "agents",
+    "ai",
+    "planning",
+    "working-context",
+    "adr",
+    "decisions"
+  ]
+}

package/template/.agents/skills/README.md

@@ -0,0 +1,6 @@
+# Project Skills
+
+Invocation-only — ask by name.
+
+- `plan-with-context` — draft a durable plan in an initiative `plan.md`.
+- `dive-into-plan` — interrogate a settled plan, distribute into initiative docs, promote to `decisions/`.