project-librarian 0.5.3 → 0.5.5

package/dist/init-project-wiki.js

@@ -7,6 +7,7 @@ const hooks_1 = require("./hooks");
 const install_skill_1 = require("./install-skill");
 const modes_1 = require("./modes");
 const migration_1 = require("./migration");
+const session_handoff_1 = require("./session-handoff");
 const templates_1 = require("./templates");
 const wiki_visualizer_1 = require("./wiki-visualizer");
 const workspace_1 = require("./workspace");
@@ -16,7 +17,7 @@ function codeIndex() {
 function printUsage() {
     console.log(`Usage:
   project-librarian [init|update] [options]
-  project-librarian install [--scope user|project] [--agents codex|claude|cursor|gemini|all]
+  project-librarian install [--scope user|project] [--agents codex|claude|cursor|gemini|all] [--dry-run]
   project-librarian mcp
 
 Options:
@@ -33,12 +34,23 @@ Options:
   --issue-draft                    Print a problem/side-effect GitHub issue body draft.
   --issue-body-file <path>         With --issue-create, use an existing Markdown body file.
   --issue-title <title>            Override the generated issue draft title.
+  --dry-run                        With install, preview copied skill files without writing them.
   --query <terms>                  Search wiki paths, metadata, titles, and bodies (answer-shaped, capped output).
   --wiki-impact <page-or-term>     Show wiki backlinks, decision_ref citations, and router depth for matching pages.
   --wiki-visualize                 Write a static wiki graph visualizer to .project-wiki/wiki-graph.html.
   --wiki-visualize-out <path>      With --wiki-visualize, write under a custom .project-wiki/ path.
   --refresh-index                  Update the managed auto-discovered wiki index block.
   --capture-inbox                  Append a candidate note with --title, --content, and optional --category.
+  --handoff-save                   Save local generated session handoff state under .project-wiki/session/.
+  --handoff-show                   Print the current local session handoff.
+  --handoff-status                 Print JSON status for the local session handoff.
+  --handoff-clear                  Remove generated session handoff files.
+  --handoff-promote-inbox          Promote selected generated handoff facts into wiki/inbox/project-candidates.md.
+  --handoff-injection-enable       Opt in to capped full handoff injection in startup hooks.
+  --handoff-injection-disable      Remove the generated full handoff injection opt-in.
+  --handoff-injection-status       Print JSON status for the full handoff injection experiment.
+  --goal, --state, --blocked       With --handoff-save, provide resume context fields.
+  --next, --decision               With --handoff-save, repeat for next actions and decisions.
   --glossary-init                  Create and route the optional glossary page.
   --agents <list>                  With init/update, write only selected agent surfaces: codex, claude, cursor, gemini, or all. Existing project skill/setup surfaces are preserved by default.
   --prune-check                    Report active pages with stale or unresolved signals.
@@ -161,6 +173,24 @@ if (args_1.codeIndexIncrementalMode && args_1.codeIndexFullMode) {
     console.error("Use one code index update mode at a time: --incremental or --code-index-full.");
     process.exit(1);
 }
+const activeHandoffModes = [
+    args_1.handoffSaveMode ? "--handoff-save" : "",
+    args_1.handoffShowMode ? "--handoff-show" : "",
+    args_1.handoffStatusMode ? "--handoff-status" : "",
+    args_1.handoffClearMode ? "--handoff-clear" : "",
+    args_1.handoffPromoteInboxMode ? "--handoff-promote-inbox" : "",
+    args_1.handoffInjectionEnableMode ? "--handoff-injection-enable" : "",
+    args_1.handoffInjectionDisableMode ? "--handoff-injection-disable" : "",
+    args_1.handoffInjectionStatusMode ? "--handoff-injection-status" : "",
+].filter(Boolean);
+if (activeHandoffModes.length > 1) {
+    console.error(`Use one session handoff mode at a time: ${activeHandoffModes.join(", ")}.`);
+    process.exit(1);
+}
+if (args_1.handoffInputMode && !args_1.handoffSaveMode) {
+    console.error("--goal, --state, --blocked, --next, --decision, --open-question, --last-success-command, --last-failure-command, and --verification are only supported with --handoff-save.");
+    process.exit(1);
+}
 if (args_1.command === "install" || args_1.command === "install-skill") {
     (0, install_skill_1.runInstallSkillMode)();
     process.exit(0);
@@ -176,6 +206,33 @@ else {
     runInitCommand();
 }
 function runInitCommand() {
+    const activeHandoffMode = activeHandoffModes[0];
+    if (activeHandoffMode) {
+        try {
+            if (args_1.handoffSaveMode)
+                (0, session_handoff_1.runHandoffSaveMode)();
+            else if (args_1.handoffShowMode)
+                (0, session_handoff_1.runHandoffShowMode)();
+            else if (args_1.handoffStatusMode)
+                (0, session_handoff_1.runHandoffStatusMode)();
+            else if (args_1.handoffClearMode)
+                (0, session_handoff_1.runHandoffClearMode)();
+            else if (args_1.handoffPromoteInboxMode)
+                (0, session_handoff_1.runHandoffPromoteInboxMode)();
+            else if (args_1.handoffInjectionEnableMode)
+                (0, session_handoff_1.runHandoffInjectionEnableMode)();
+            else if (args_1.handoffInjectionDisableMode)
+                (0, session_handoff_1.runHandoffInjectionDisableMode)();
+            else if (args_1.handoffInjectionStatusMode)
+                (0, session_handoff_1.runHandoffInjectionStatusMode)();
+            exitAfterStdoutDrain(0);
+        }
+        catch (error) {
+            console.error(error instanceof Error ? error.message : String(error));
+            process.exit(1);
+        }
+        return;
+    }
     const activeCodeModes = activeCodeEvidenceCliModes();
     if (activeCodeModes.length > 1) {
         console.error("Use one code evidence mode at a time: --code-index, --code-index-health, --code-query, --code-report, --code-status, --code-files, --code-impact, --code-context-pack, or --code-search-symbol.");

package/dist/install-skill.js

@@ -112,26 +112,119 @@ function installTarget(agent, scope) {
     const base = scope === "user" ? userAgentRoot(agent) : path.join(process.cwd(), projectAgentRoot(agent));
     return path.join(base, "skills", skillName);
 }
+function assertNoTargetSymlink(targetRoot, target, includeLeaf) {
+    const rootResolved = path.resolve(targetRoot);
+    const targetResolved = path.resolve(target);
+    if (targetResolved !== rootResolved && !targetResolved.startsWith(`${rootResolved}${path.sep}`)) {
+        fail(`skill install target escaped target root: ${target}`);
+    }
+    if (fs.existsSync(rootResolved) && fs.lstatSync(rootResolved).isSymbolicLink()) {
+        fail("skill install refuses to follow destination symlink: .");
+    }
+    const relative = path.relative(rootResolved, targetResolved);
+    const parts = relative ? relative.split(path.sep).filter(Boolean) : [];
+    const checkedParts = includeLeaf ? parts : parts.slice(0, -1);
+    let current = rootResolved;
+    for (const part of checkedParts) {
+        current = path.join(current, part);
+        if (!fs.existsSync(current))
+            continue;
+        const stat = fs.lstatSync(current);
+        if (stat.isSymbolicLink()) {
+            fail(`skill install refuses to follow destination symlink: ${path.relative(rootResolved, current) || "."}`);
+        }
+        if (current !== targetResolved && !stat.isDirectory()) {
+            fail(`skill install target has a non-directory path component: ${path.relative(rootResolved, current)}`);
+        }
+    }
+}
+function isInsidePath(base, target) {
+    const baseResolved = path.resolve(base);
+    const targetResolved = path.resolve(target);
+    return targetResolved === baseResolved || targetResolved.startsWith(`${baseResolved}${path.sep}`);
+}
+function mkdirFromBaseNoSymlink(base, target) {
+    const baseResolved = path.resolve(base);
+    const targetResolved = path.resolve(target);
+    if (!isInsidePath(baseResolved, targetResolved)) {
+        fail(`skill install target escaped checked base: ${target}`);
+    }
+    let current = baseResolved;
+    const parts = path.relative(baseResolved, targetResolved).split(path.sep).filter(Boolean);
+    for (const part of parts) {
+        current = path.join(current, part);
+        if (fs.existsSync(current)) {
+            const stat = fs.lstatSync(current);
+            if (stat.isSymbolicLink()) {
+                fail(`skill install refuses to follow destination symlink: ${path.relative(baseResolved, current)}`);
+            }
+            if (!stat.isDirectory()) {
+                fail(`skill install target has a non-directory path component: ${path.relative(baseResolved, current)}`);
+            }
+            continue;
+        }
+        fs.mkdirSync(current);
+    }
+}
+function mkdirpNoTargetSymlink(targetRoot, target) {
+    const rootResolved = path.resolve(targetRoot);
+    const targetResolved = path.resolve(target);
+    const cwdResolved = path.resolve(process.cwd());
+    if (isInsidePath(cwdResolved, rootResolved)) {
+        mkdirFromBaseNoSymlink(cwdResolved, rootResolved);
+    }
+    else {
+        fs.mkdirSync(rootResolved, { recursive: true });
+    }
+    const relative = path.relative(rootResolved, targetResolved);
+    let current = rootResolved;
+    if (!relative) {
+        if (fs.existsSync(current) && fs.lstatSync(current).isSymbolicLink()) {
+            fail("skill install refuses to follow destination symlink: .");
+        }
+        if (!fs.existsSync(current))
+            fs.mkdirSync(current);
+        return;
+    }
+    for (const part of relative.split(path.sep).filter(Boolean)) {
+        current = path.join(current, part);
+        if (fs.existsSync(current)) {
+            const stat = fs.lstatSync(current);
+            if (stat.isSymbolicLink()) {
+                fail(`skill install refuses to follow destination symlink: ${path.relative(rootResolved, current)}`);
+            }
+            if (!stat.isDirectory()) {
+                fail(`skill install target has a non-directory path component: ${path.relative(rootResolved, current)}`);
+            }
+            continue;
+        }
+        fs.mkdirSync(current);
+    }
+}
 function sameFile(source, target) {
-    if (!fs.existsSync(target) || !fs.statSync(target).isFile())
+    if (!fs.existsSync(target))
+        return false;
+    const stat = fs.lstatSync(target);
+    if (stat.isSymbolicLink() || !stat.isFile())
         return false;
     return fs.readFileSync(source).equals(fs.readFileSync(target));
 }
-function copyPath(source, target, dryRun) {
+function copyPath(source, target, targetRoot, dryRun) {
     if (!fs.existsSync(source))
         fail(`missing package file: ${source}`);
     const existed = fs.existsSync(target);
     if (dryRun)
         return "dry-run";
     const sourceStat = fs.statSync(source);
+    assertNoTargetSymlink(targetRoot, target, true);
     if (sourceStat.isDirectory()) {
-        fs.mkdirSync(target, { recursive: true });
+        mkdirpNoTargetSymlink(targetRoot, target);
         for (const entry of fs.readdirSync(source, { withFileTypes: true })) {
-            copyPath(path.join(source, entry.name), path.join(target, entry.name), false);
+            copyPath(path.join(source, entry.name), path.join(target, entry.name), targetRoot, false);
         }
         return existed ? "updated" : "created";
     }
-    fs.mkdirSync(path.dirname(target), { recursive: true });
+    mkdirpNoTargetSymlink(targetRoot, path.dirname(target));
     if (sameFile(source, target))
         return "exists";
     fs.copyFileSync(source, target);
@@ -146,7 +239,7 @@ function copyPackageFiles(targetRoot, dryRun, labelRoot = targetRoot) {
     return packageFiles.map((relativePath) => {
         const source = path.join(root, relativePath);
         const target = path.join(targetRoot, relativePath);
-        return [path.join(labelRoot, relativePath), copyPath(source, target, dryRun)];
+        return [path.join(labelRoot, relativePath), copyPath(source, target, targetRoot, dryRun)];
     });
 }
 function syncProjectSkillInstall(agent) {

package/dist/mcp-server.js

@@ -1,10 +1,10 @@
 "use strict";
 // Hand-rolled MCP stdio server for the code-evidence index.
 //
-// Why hand-rolled: the product holds a zero-runtime-dependency posture (only
-// node:sqlite plus optional tree-sitter grammars). Adopting @modelcontextprotocol/sdk
-// would add a hard runtime dependency, so we implement the small slice of MCP we
-// need directly: JSON-RPC 2.0 over newline-delimited JSON on stdio.
+// Why hand-rolled: the package keeps the MCP surface dependency-light. Code
+// evidence already depends on node:sqlite, the package's TypeScript dependency,
+// and optional tree-sitter grammars; adopting @modelcontextprotocol/sdk would add
+// another hard runtime dependency for a small stdio slice.
 //
 // Transport: MCP stdio transport carries one JSON-RPC message per line on stdin
 // and stdout (newline-delimited JSON, "ndjson"); stderr is free for logging. We

package/dist/migration.js

@@ -57,6 +57,7 @@ exports.migrationCoverageStatusMap = migrationCoverageStatusMap;
 exports.semanticStatusForInboxStatus = semanticStatusForInboxStatus;
 exports.runReviewMigrationMode = runReviewMigrationMode;
 const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
 const taxonomy_1 = require("./taxonomy");
 const workspace_1 = require("./workspace");
 const templates_1 = require("./templates");
@@ -317,9 +318,31 @@ function activeMigrationLegacyRoots() {
     const verifiedRoot = migrationVerificationLegacyRoot();
     return verifiedRoot ? [verifiedRoot] : legacyWikiRoots();
 }
+function migrationDirectoryPath(relativePath) {
+    const resolved = path.resolve(workspace_1.root, relativePath);
+    const rootResolved = path.resolve(workspace_1.root);
+    if (resolved !== rootResolved && !resolved.startsWith(`${rootResolved}${path.sep}`)) {
+        throw new Error(`migration directory must stay inside the project root: ${relativePath}`);
+    }
+    const stat = fs.lstatSync(resolved);
+    if (stat.isSymbolicLink()) {
+        throw new Error(`migration refuses to follow symlinked wiki directory: ${relativePath}`);
+    }
+    if (!stat.isDirectory()) {
+        throw new Error(`migration path is not a directory: ${relativePath}`);
+    }
+    const realPath = fs.realpathSync(resolved);
+    if (realPath !== rootResolved && !realPath.startsWith(`${rootResolved}${path.sep}`)) {
+        throw new Error(`migration directory must resolve inside the project root: ${relativePath}`);
+    }
+    return resolved;
+}
 function expectedMigrationUnits() {
     return activeMigrationLegacyRoots()
-        .flatMap((legacyRoot) => (0, wiki_files_1.walkMarkdownFiles)((0, workspace_1.abs)(legacyRoot), [], (0, workspace_1.abs)(legacyRoot)))
+        .flatMap((legacyRoot) => {
+        const legacyPath = migrationDirectoryPath(legacyRoot);
+        return (0, wiki_files_1.walkMarkdownFiles)(legacyPath, [], legacyPath);
+    })
         .flatMap((file) => extractMigrationUnits(file.basePath, (0, workspace_1.read)(file.path)));
 }
 function loadMigrationUnitContext() {
@@ -962,6 +985,7 @@ function nextLegacyPath() {
 }
 function prepareMigrationMode() {
     if ((0, workspace_1.exists)("wiki")) {
+        migrationDirectoryPath("wiki");
         const legacyPath = nextLegacyPath();
         fs.renameSync((0, workspace_1.abs)("wiki"), (0, workspace_1.abs)(legacyPath));
         return { legacyPath, note: `moved wiki to ${legacyPath}` };
@@ -981,7 +1005,8 @@ function migrationTargetForKind(kind) {
 }
 function runMigrationMode(migrationState) {
     const legacyPath = migrationState.legacyPath;
-    const markdownFiles = legacyPath && (0, workspace_1.exists)(legacyPath) ? (0, wiki_files_1.walkMarkdownFiles)((0, workspace_1.abs)(legacyPath), [], (0, workspace_1.abs)(legacyPath)) : [];
+    const legacyRootPath = legacyPath && (0, workspace_1.exists)(legacyPath) ? migrationDirectoryPath(legacyPath) : "";
+    const markdownFiles = legacyRootPath ? (0, wiki_files_1.walkMarkdownFiles)(legacyRootPath, [], legacyRootPath) : [];
     const fileRecords = markdownFiles.map((file) => {
         const text = (0, workspace_1.read)(file.path);
         return { file, text, formOnlyReason: formOnlyMigrationDocumentReason(file.basePath, text) };

package/dist/modes.js

@@ -37,6 +37,7 @@ exports.buildRefreshIndexBlock = buildRefreshIndexBlock;
 exports.runQueryMode = runQueryMode;
 exports.runWikiImpactMode = runWikiImpactMode;
 exports.projectCandidatesContent = projectCandidatesContent;
+exports.appendProjectCandidate = appendProjectCandidate;
 exports.appendCaptureInbox = appendCaptureInbox;
 exports.runIssueDraftMode = runIssueDraftMode;
 exports.runIssueCreateMode = runIssueCreateMode;
@@ -338,23 +339,29 @@ function projectCandidatesContent() {
 | --- | --- | --- | --- | --- |
 `;
 }
-function appendCaptureInbox() {
+function appendProjectCandidate(input = {}) {
     (0, workspace_1.mkdirp)("wiki/inbox");
     const relativePath = "wiki/inbox/project-candidates.md";
     const existed = (0, workspace_1.exists)(relativePath);
     if (!existed)
         (0, workspace_1.write)(relativePath, projectCandidatesContent());
-    if (!args_1.captureTitle && !args_1.captureContent)
+    const candidateTitle = input.title ?? args_1.captureTitle;
+    const candidateContent = input.content ?? args_1.captureContent;
+    const candidateCategory = input.category ?? args_1.captureCategory;
+    if (!candidateTitle && !candidateContent)
         return existed ? "exists" : "created";
-    const title = (args_1.captureTitle || "Untitled candidate").replace(/\|/g, "/");
-    const content = (args_1.captureContent || "").replace(/\r?\n/g, "<br>").replace(/\|/g, "/");
-    const row = `| ${workspace_1.today} | ${title} | ${args_1.captureCategory.replace(/\|/g, "/")} | ${content} | pending |`;
+    const title = (candidateTitle || "Untitled candidate").replace(/\|/g, "/");
+    const content = (candidateContent || "").replace(/\r?\n/g, "<br>").replace(/\|/g, "/");
+    const row = `| ${workspace_1.today} | ${title} | ${candidateCategory.replace(/\|/g, "/")} | ${content} | pending |`;
     const current = (0, workspace_1.read)(relativePath);
     if (current.includes(row))
         return "exists";
     (0, workspace_1.write)(relativePath, `${current.trimEnd()}\n${row}\n`);
     return "updated";
 }
+function appendCaptureInbox() {
+    return appendProjectCandidate();
+}
 function gitOutput(args) {
     try {
         return childProcess.execFileSync("git", args, {