bitacora-cli 1.1.0 → 1.1.1

package/README.md

@@ -15,6 +15,7 @@ bitacora --help
 ```
 
 Use `--root <path>` on any command to target a different project directory.
+Command examples are available in `examples/cli-workflows.md`.
 
 ## What Each Bitacora File Stores
 
@@ -50,23 +51,30 @@ Bitacora now supports compacting finished tracks to reduce active context size a
 
 If gates fail, command exits with code `1` and no compaction is applied.
 
+## New in v1.1.1: Skill-only update
+
+Use `bitacora skill` to install/update only `.agents/skills/bitacora/SKILL.md` and `skills-lock.json` without recreating `bitacora/` context files.
+
 ## Typical flow
 
 ```bash
 # 1) bootstrap
 bitacora init
 
-# 2) create work
+# 2) update skill only (after CLI upgrades)
+bitacora skill
+
+# 3) create work
 bitacora new-track
 
-# 3) append progress
+# 4) append progress
 bitacora log --track-id TRACK-001 --message "implemented parser"
 bitacora log --track-id TRACK-001 --message "TEST: npm test -- --run tests/core/parser.test.ts -> pass"
 
-# 4) compact when fully completed
+# 5) compact when fully completed
 bitacora compact --track-id TRACK-001 --complete
 
-# 5) inspect archive only when needed
+# 6) inspect archive only when needed
 bitacora history --track-id TRACK-001
 bitacora history --track-id TRACK-001 --show
 ```
@@ -80,6 +88,14 @@ Creates the `bitacora/` memory structure in the project root.
 - `--force`: recreates memory files if they already exist.
 - `--root <path>`: sets the project root (default: current directory).
 
+### `bitacora skill [--root <path>]`
+
+Installs or updates only the Bitacora local agent skill and its lock entry.
+
+- Updates `.agents/skills/bitacora/SKILL.md`.
+- Updates `skills-lock.json` entry for `bitacora` while preserving other skills.
+- Does not recreate or modify `bitacora/` project memory files.
+
 ### `bitacora new-track [trackId] [--status <status>] [--priority <priority>] [--root <path>]`
 
 Creates a new track file. If `trackId` is omitted, Bitacora picks the next sequential ID.
@@ -106,6 +122,13 @@ Compacts tracks by summarizing content and archiving full detail.
 - `--complete`: mark target tracks as completed (requires completion gates).
 - `--dry-run`: report estimated byte/token savings without writing files.
 - `--root <path>`: sets the project root.
+- `--complete` gates:
+  - `# Tasks` must not contain unchecked items (`- [ ]`).
+  - `# Log` must include at least one `TEST:` line.
+- rewrite/archive model:
+  - full source track is archived under `bitacora/history/TRACK-###.md`.
+  - active `tracks/TRACK-###/track.md` is rewritten into compact summary form.
+  - `tracks/tracks.md` is regenerated and the previous snapshot is archived in `bitacora/history/tracks-*.md`.
 
 Examples:
 
@@ -131,6 +154,15 @@ Reads archived track history.
 - `--show`: print full archived content (default prints only metadata/path).
 - `--root <path>`: sets the project root.
 
+### `bitacora --help`
+
+`bitacora --help` includes full command details for:
+- `init`, `skill`, `new-track`, `validate`, `rebuild-state`, `log`
+- `compact` (flags, completion gates, output/archive model)
+- `history` (metadata mode vs `--show`)
+
+For a maintained example output, see `examples/help-output.txt`.
+
 ### `bitacora validate [--json] [--root <path>]`
 
 Validates the Bitacora file/folder structure and reports errors.

package/dist/src/cli.js

@@ -10,6 +10,7 @@ const history_1 = require("./commands/history");
 const log_1 = require("./commands/log");
 const new_track_1 = require("./commands/new-track");
 const rebuild_state_1 = require("./commands/rebuild-state");
+const skill_1 = require("./commands/skill");
 const validate_1 = require("./commands/validate");
 const COMMAND_HELP_OVERVIEW = `
 Command details:
@@ -19,6 +20,11 @@ Command details:
       --force        Recreate bitacora memory if it already exists.
       --root <path>  Project root path (default: current directory).
 
+  skill
+    Installs or updates only the bitacora agent skill and skills lock entry.
+    Options:
+      --root <path>  Project root path (default: current directory).
+
   new-track [trackId]
     Creates a new track file, automatically picking the next track id when omitted.
     Options:
@@ -52,6 +58,13 @@ Command details:
       --complete            Mark target tracks as completed (requires completion gates).
       --dry-run             Show savings without modifying files.
       --root <path>         Project root path (default: current directory).
+    Completion gates (--complete):
+      - # Tasks has no unchecked item (- [ ]).
+      - # Log includes at least one line containing TEST:.
+    Output model:
+      - Full source moves to bitacora/history/TRACK-###.md.
+      - Active track.md is rewritten into compact summary form.
+      - tracks/tracks.md is regenerated; previous snapshot is archived in history/.
 
   history
     Reads archived history for a compacted track.
@@ -59,6 +72,9 @@ Command details:
       --track-id <trackId>  Track identifier.
       --show                Print full archived content.
       --root <path>         Project root path (default: current directory).
+    Notes:
+      - Without --show, prints metadata/path only.
+      - Use --show only when compact summary is insufficient.
 `;
 function writeLine(writer, message) {
     writer(message.endsWith("\n") ? message : `${message}\n`);
@@ -91,6 +107,18 @@ function createCliProgram(runtime = {}, onCommandExitCode) {
         });
         onCommandExitCode?.(exitCode);
     });
+    program
+        .command("skill")
+        .description("Install or update only the bitacora agent skill.")
+        .option("--root <path>", "project root path")
+        .action((options) => {
+        const exitCode = (0, skill_1.runSkillCommand)({
+            rootDir: options.root ?? cwd()
+        }, {
+            onError: (message) => writeLine(stderr, message)
+        });
+        onCommandExitCode?.(exitCode);
+    });
     program
         .command("new-track [trackId]")
         .description("Create a new track with optional id, status, and priority.")
@@ -217,6 +245,9 @@ async function runCli(argv, runtime = {}) {
     }
     catch (error) {
         if (error instanceof commander_1.CommanderError) {
+            if (error.code === "commander.helpDisplayed") {
+                return 0;
+            }
             return commandExitCode !== 0 ? commandExitCode : 1;
         }
         throw error;

package/dist/src/commands/init.js

@@ -6,63 +6,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.runInitCommand = runInitCommand;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
-const node_crypto_1 = require("node:crypto");
 const templates_1 = require("../core/templates");
-function computeHash(content) {
-    return (0, node_crypto_1.createHash)("sha256").update(content).digest("hex");
-}
-function readSkillsLockFile(filePath) {
-    if (!node_fs_1.default.existsSync(filePath)) {
-        return {
-            version: 1,
-            skills: {}
-        };
-    }
-    try {
-        const parsed = JSON.parse(node_fs_1.default.readFileSync(filePath, "utf8"));
-        if (typeof parsed !== "object" || parsed === null) {
-            return { version: 1, skills: {} };
-        }
-        const versionRaw = parsed.version;
-        const skillsRaw = parsed.skills;
-        const normalized = {};
-        if (typeof skillsRaw === "object" && skillsRaw !== null) {
-            for (const [name, value] of Object.entries(skillsRaw)) {
-                if (typeof value !== "object" || value === null) {
-                    continue;
-                }
-                const source = value.source;
-                const sourceType = value.sourceType;
-                const computedHash = value.computedHash;
-                if (typeof source === "string" &&
-                    typeof sourceType === "string" &&
-                    typeof computedHash === "string") {
-                    normalized[name] = { source, sourceType, computedHash };
-                }
-            }
-        }
-        return {
-            version: typeof versionRaw === "number" ? versionRaw : 1,
-            skills: normalized
-        };
-    }
-    catch {
-        return {
-            version: 1,
-            skills: {}
-        };
-    }
-}
-function writeSkillsLockFile(rootDir, skillContent) {
-    const lockPath = node_path_1.default.join(rootDir, "skills-lock.json");
-    const lock = readSkillsLockFile(lockPath);
-    lock.skills.bitacora = {
-        source: ".agents/skills/bitacora/SKILL.md",
-        sourceType: "local",
-        computedHash: computeHash(skillContent)
-    };
-    node_fs_1.default.writeFileSync(lockPath, `${JSON.stringify(lock, null, 2)}\n`, "utf8");
-}
+const skill_installer_1 = require("../core/skill-installer");
 function runInitCommand(options, dependencies = {}) {
     const now = dependencies.now ?? (() => new Date().toISOString());
     const onError = dependencies.onError ?? (() => { });
@@ -79,15 +24,12 @@ function runInitCommand(options, dependencies = {}) {
     const trackId = "TRACK-001";
     node_fs_1.default.mkdirSync(node_path_1.default.join(memoryRoot, "tracks", trackId), { recursive: true });
     node_fs_1.default.mkdirSync(node_path_1.default.join(memoryRoot, "history"), { recursive: true });
-    node_fs_1.default.mkdirSync(node_path_1.default.join(options.rootDir, ".agents", "skills", "bitacora"), { recursive: true });
     node_fs_1.default.writeFileSync(node_path_1.default.join(memoryRoot, "product.md"), (0, templates_1.createProductTemplate)(), "utf8");
     node_fs_1.default.writeFileSync(node_path_1.default.join(memoryRoot, "tech-stack.md"), (0, templates_1.createTechStackTemplate)(), "utf8");
     node_fs_1.default.writeFileSync(node_path_1.default.join(memoryRoot, "workflow.md"), (0, templates_1.createWorkflowTemplate)(), "utf8");
     node_fs_1.default.writeFileSync(node_path_1.default.join(memoryRoot, "ux-style-guide.md"), (0, templates_1.createUxStyleGuideTemplate)(), "utf8");
     node_fs_1.default.writeFileSync(node_path_1.default.join(memoryRoot, "index.md"), (0, templates_1.createIndexTemplate)(), "utf8");
-    const skillContent = (0, templates_1.createAgentSkillTemplate)();
-    node_fs_1.default.writeFileSync(node_path_1.default.join(options.rootDir, ".agents", "skills", "bitacora", "SKILL.md"), skillContent, "utf8");
-    writeSkillsLockFile(options.rootDir, skillContent);
+    (0, skill_installer_1.installBitacoraSkill)(options.rootDir);
     node_fs_1.default.writeFileSync(node_path_1.default.join(memoryRoot, "tracks", "tracks.md"), (0, templates_1.createTracksRegistryTemplate)(createdOnDate), "utf8");
     node_fs_1.default.writeFileSync(node_path_1.default.join(memoryRoot, "tracks", "tracks-template.md"), (0, templates_1.createTracksTemplate)(), "utf8");
     node_fs_1.default.writeFileSync(node_path_1.default.join(memoryRoot, "tracks", trackId, "track.md"), (0, templates_1.createTrackTemplate)(trackId, "active", "medium", createdAt), "utf8");

package/dist/src/commands/skill.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runSkillCommand = runSkillCommand;
+const skill_installer_1 = require("../core/skill-installer");
+function runSkillCommand(options, dependencies = {}) {
+    const onError = dependencies.onError ?? (() => { });
+    try {
+        (0, skill_installer_1.installBitacoraSkill)(options.rootDir);
+        return 0;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        onError(message);
+        return 1;
+    }
+}

package/dist/src/core/skill-installer.js

@@ -0,0 +1,72 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installBitacoraSkill = installBitacoraSkill;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+const templates_1 = require("./templates");
+function computeHash(content) {
+    return (0, node_crypto_1.createHash)("sha256").update(content).digest("hex");
+}
+function readSkillsLockFile(filePath) {
+    if (!node_fs_1.default.existsSync(filePath)) {
+        return {
+            version: 1,
+            skills: {}
+        };
+    }
+    try {
+        const parsed = JSON.parse(node_fs_1.default.readFileSync(filePath, "utf8"));
+        if (typeof parsed !== "object" || parsed === null) {
+            return { version: 1, skills: {} };
+        }
+        const versionRaw = parsed.version;
+        const skillsRaw = parsed.skills;
+        const normalized = {};
+        if (typeof skillsRaw === "object" && skillsRaw !== null) {
+            for (const [name, value] of Object.entries(skillsRaw)) {
+                if (typeof value !== "object" || value === null) {
+                    continue;
+                }
+                const source = value.source;
+                const sourceType = value.sourceType;
+                const computedHash = value.computedHash;
+                if (typeof source === "string" &&
+                    typeof sourceType === "string" &&
+                    typeof computedHash === "string") {
+                    normalized[name] = { source, sourceType, computedHash };
+                }
+            }
+        }
+        return {
+            version: typeof versionRaw === "number" ? versionRaw : 1,
+            skills: normalized
+        };
+    }
+    catch {
+        return {
+            version: 1,
+            skills: {}
+        };
+    }
+}
+function writeSkillsLockFile(rootDir, skillContent) {
+    const lockPath = node_path_1.default.join(rootDir, "skills-lock.json");
+    const lock = readSkillsLockFile(lockPath);
+    lock.skills.bitacora = {
+        source: ".agents/skills/bitacora/SKILL.md",
+        sourceType: "local",
+        computedHash: computeHash(skillContent)
+    };
+    node_fs_1.default.writeFileSync(lockPath, `${JSON.stringify(lock, null, 2)}\n`, "utf8");
+}
+function installBitacoraSkill(rootDir) {
+    const skillDir = node_path_1.default.join(rootDir, ".agents", "skills", "bitacora");
+    node_fs_1.default.mkdirSync(skillDir, { recursive: true });
+    const skillContent = (0, templates_1.createAgentSkillTemplate)();
+    node_fs_1.default.writeFileSync(node_path_1.default.join(skillDir, "SKILL.md"), skillContent, "utf8");
+    writeSkillsLockFile(rootDir, skillContent);
+}

package/dist/src/core/templates.js

@@ -169,7 +169,7 @@ function createAgentSkillTemplate() {
     return `---
 name: bitacora
 description: Keep deterministic project memory in bitacora/ and update it continuously during implementation sessions.
-version: 1.0.0
+version: 1.1.1
 type: local
 source: .agents/skills/bitacora/SKILL.md
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bitacora-cli",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Deterministic agent-oriented project memory system. Provides structured Markdown-based long-term memory, strict validation, state reconstruction, and an enforcement CLI with agent skill integration to guide and limit agent behavior.",
   "repository": {
     "type": "git",