durable-context 1.1.0 → 1.1.1

package/README.md

@@ -28,6 +28,13 @@ Skills are invocation-only — they do not run automatically.
 Use `project-profile-baseline` once to populate repo-wide commands and
 operating facts; use `project-profile-refresh` when those stable facts change.
 
-Options: `--target`, `--dry-run`, `--force`, `status`.
+Update managed agent assets without replacing project work:
+
+```bash
+npx durable-context@latest update
+```
+
+Commands/options: `update`, `status`, `--target`, `--dry-run`, and `--force`
+for `init`.
 
 For release-anchored documentation, see the `reference-docs` package.

package/lib/installer.js

@@ -36,12 +36,12 @@ export async function runCli(config, argv) {
     return;
   }
 
-  if (args.command !== 'init') {
+  if (args.command !== 'init' && args.command !== 'update') {
     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 projectName = await resolveProjectName(config, args, targetRoot);
   const installer = new Installer({
     config,
     targetRoot,
@@ -50,7 +50,12 @@ export async function runCli(config, argv) {
     dryRun: args.dryRun
   });
 
-  await installer.init();
+  if (args.command === 'init') {
+    await installer.init();
+    return;
+  }
+
+  await installer.update();
 }
 
 function parseArgs(argv, config) {
@@ -143,21 +148,24 @@ function printHelp(config) {
 
 Usage:
   ${config.cliName} init [options]
+  ${config.cliName} update [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.
+  --force                  Replace existing generated directories during init.
   --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}@latest update
   npx ${config.packageJson.name}@${config.packageJson.version} init --project-name "My App"
   npx ${config.packageJson.name} status --target ../existing-project
 
+The update command refreshes managed agent assets without replacing project work.
 The status command reads ${config.metadataPath} from an initialized project.
 `);
 }
@@ -176,6 +184,22 @@ async function inferProjectName(targetRoot) {
   return path.basename(targetRoot);
 }
 
+async function resolveProjectName(config, args, targetRoot) {
+  if (args.projectName) {
+    return args.projectName;
+  }
+
+  if (args.command === 'update') {
+    const metadata = await readOptionalJson(path.join(targetRoot, config.metadataPath));
+
+    if (typeof metadata?.projectName === 'string' && metadata.projectName.trim()) {
+      return metadata.projectName;
+    }
+  }
+
+  return inferProjectName(targetRoot);
+}
+
 class Installer {
   constructor({ config, targetRoot, projectName, force, dryRun }) {
     this.config = config;
@@ -199,6 +223,16 @@ class Installer {
     this.printSummary();
   }
 
+  async update() {
+    await this.ensureDirectory(this.targetRoot);
+
+    await this.installAgentsFile();
+    await this.updateSkills();
+    await this.writeMetadata();
+
+    this.printSummary();
+  }
+
   async installPayloadRoots() {
     const entries = await readdir(this.templateDir, { withFileTypes: true });
 
@@ -290,6 +324,22 @@ class Installer {
       );
     }
 
+    await this.upsertSkillsReadme();
+  }
+
+  async updateSkills() {
+    for (const skill of this.config.skills) {
+      await this.copyTemplatePath(
+        `${agentsSkillsRelative}/${skill.name}`,
+        `${agentsSkillsRelative}/${skill.name}`,
+        { replaceExisting: true }
+      );
+    }
+
+    await this.upsertSkillsReadme();
+  }
+
+  async upsertSkillsReadme() {
     const readmeTarget = await this.findExistingTargetPath(`${agentsSkillsRelative}/README.md`);
     const readmePath = readmeTarget.exists
       ? readmeTarget.path
@@ -302,29 +352,55 @@ class Installer {
     }
 
     const current = await readFile(readmePath, 'utf8');
-    const missingSkills = this.config.skills.filter((skill) => !current.includes(skill.name));
+    const section = this.renderSkillsReadmeSection();
+    const { start, end } = this.skillsReadmeMarkers();
+
+    if (current.includes(start) && current.includes(end)) {
+      const updated = current.replace(
+        new RegExp(`${escapeRegExp(start)}[\\s\\S]*?${escapeRegExp(end)}`),
+        section
+      );
 
-    if (missingSkills.length === 0) {
-      this.note(`${readmeDisplay} already lists the ${this.config.summaryLabel} skills`);
+      if (updated === current) {
+        this.note(`${readmeDisplay} already has the ${this.config.summaryLabel} skills section`);
+        return;
+      }
+
+      await this.writeFile(readmePath, updated, `update ${readmeDisplay} ${this.config.summaryLabel} skills section`);
       return;
     }
 
-    const entry = [
-      '',
-      `## ${this.config.summaryLabel} Skills`,
-      '',
-      ...missingSkills.map((skill) => skill.readmeEntry),
-      ''
-    ].join('\n');
+    const separator = current.endsWith('\n\n') ? '' : current.endsWith('\n') ? '\n' : '\n\n';
 
     await this.writeFile(
       readmePath,
-      `${current.trimEnd()}\n${entry}`,
+      `${current}${separator}${section}\n`,
       `append ${this.config.summaryLabel} skills to ${readmeDisplay}`
     );
   }
 
-  async copyTemplatePath(sourceRelative, targetRelative) {
+  skillsReadmeMarkers() {
+    const name = this.config.packageJson.name;
+
+    return {
+      start: `<!-- ${name}:skills:start -->`,
+      end: `<!-- ${name}:skills:end -->`
+    };
+  }
+
+  renderSkillsReadmeSection() {
+    const { start, end } = this.skillsReadmeMarkers();
+
+    return [
+      start,
+      `## ${this.config.summaryLabel} Skills`,
+      '',
+      ...this.config.skills.map((skill) => skill.readmeEntry),
+      end
+    ].join('\n');
+  }
+
+  async copyTemplatePath(sourceRelative, targetRelative, { replaceExisting = this.force } = {}) {
     const sourcePath = path.join(this.templateDir, sourceRelative);
     const targetInfo = await this.findExistingTargetPath(targetRelative);
 
@@ -337,7 +413,7 @@ class Installer {
     if (targetInfo.exists) {
       const variantNote = targetInfo.caseVariant ? ` at ${targetInfo.display}` : '';
 
-      if (!this.force) {
+      if (!replaceExisting) {
         this.note(`skip ${targetRelative} (already exists${variantNote}; use --force to replace)`);
         return false;
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "durable-context",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Invocation-only skills and scaffold for durable planning: initiatives in context/, decisions in an append-only log.",
   "license": "MIT",
   "type": "module",

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

@@ -1,9 +1,13 @@
 # Project Skills
 
-Invocation-only — ask by name.
+Invocation-only - ask by name.
 
-- `project-profile-baseline` — populate `context/project-profile.md` from source-backed repo facts.
-- `project-profile-refresh` — refresh stable repo-wide profile facts after repo changes or release documentation refreshes.
-- `plan-with-context` — draft a durable plan in an initiative `plan.md`.
-- `devils-advocate` — critique a draft plan before distribution.
-- `dive-into-plan` — interrogate a settled plan, distribute into initiative docs, promote to `decisions/`.
+<!-- durable-context:skills:start -->
+## Durable Context Skills
+
+- `project-profile-baseline` - invoke explicitly to populate `context/project-profile.md` from source-backed repo facts.
+- `project-profile-refresh` - invoke explicitly to refresh stable repo-wide facts in `context/project-profile.md`.
+- `plan-with-context` - invoke explicitly to draft a durable plan in an initiative `plan.md`.
+- `devils-advocate` - invoke explicitly to challenge a draft plan before distribution.
+- `dive-into-plan` - invoke explicitly to interrogate a settled plan, distribute it into initiative docs, and promote decisions.
+<!-- durable-context:skills:end -->