@anthropologies/claudestory 0.1.4 → 0.1.6

package/dist/index.d.ts

@@ -573,6 +573,7 @@ declare function guardPath(target: string, root: string): Promise<void>;
  *
  * CLAUDESTORY_PROJECT_ROOT env var overrides walk-up discovery.
  * Returns the canonical absolute path, or null if not found.
+ * Throws ProjectLoaderError if .story/ exists but is unreadable.
  */
 declare function discoverProjectRoot(startDir?: string): string | null;
 
@@ -1364,6 +1365,7 @@ declare function formatInitResult(result: {
 }, format: OutputFormat): string;
 declare function formatHandoverList(filenames: readonly string[], format: OutputFormat): string;
 declare function formatHandoverContent(filename: string, content: string, format: OutputFormat): string;
+declare function formatHandoverCreateResult(filename: string, format: OutputFormat): string;
 
 declare function formatSnapshotResult(result: {
     filename: string;
@@ -1373,4 +1375,4 @@ declare function formatSnapshotResult(result: {
 declare function formatRecap(recap: RecapResult, state: ProjectState, format: OutputFormat): string;
 declare function formatExport(state: ProjectState, mode: "all" | "phase", phaseId: string | null, format: OutputFormat): string;
 
-export { type Blocker, BlockerSchema, CURRENT_SCHEMA_VERSION, type Config, ConfigSchema, DATE_REGEX, DateSchema, ERROR_CODES, type ErrorCode, type ErrorEnvelope, ExitCode, type ExitCodeValue, type Features, FeaturesSchema, INTEGRITY_WARNING_TYPES, ISSUE_ID_REGEX, ISSUE_SEVERITIES, ISSUE_STATUSES, type InitOptions, type InitResult, type Issue, IssueIdSchema, IssueSchema, type IssueSeverity, type IssueStatus, type LoadOptions, type LoadResult, type LoadWarning, type LoadWarningType, type NextTicketAllBlocked, type NextTicketAllComplete, type NextTicketEmpty, type NextTicketOutcome, type NextTicketResult, OUTPUT_FORMATS, type OutputFormat, type PartialEnvelope, type Phase, PhaseSchema, type PhaseStatus, type PhaseWithStatus, ProjectLoaderError, ProjectState, type RecapResult, type Roadmap, RoadmapSchema, type SnapshotDiff, type SnapshotV1, SnapshotV1Schema, type SuccessEnvelope, TICKET_ID_REGEX, TICKET_STATUSES, TICKET_TYPES, type Ticket, TicketIdSchema, TicketSchema, type TicketStatus, type TicketType, type UmbrellaProgress, type UnblockImpact, type ValidationFinding, type ValidationLevel, type ValidationResult, type WithProjectLockOptions, atomicWrite, blockedTickets, buildRecap, currentPhase, deleteIssue, deleteTicket, diffStates, discoverProjectRoot, errorEnvelope, escapeMarkdownInline, extractHandoverDate, fencedBlock, formatBlockedTickets, formatBlockerList, formatError, formatExport, formatHandoverContent, formatHandoverList, formatInitResult, formatIssue, formatIssueList, formatNextTicketOutcome, formatPhaseList, formatPhaseTickets, formatRecap, formatSnapshotResult, formatStatus, formatTicket, formatTicketList, formatValidation, guardPath, initProject, isBlockerCleared, listHandovers, loadLatestSnapshot, loadProject, mergeValidation, nextIssueID, nextOrder, nextTicket, nextTicketID, partialEnvelope, phasesWithStatus, readHandover, runTransaction, runTransactionUnlocked, saveSnapshot, serializeJSON, sortKeysDeep, successEnvelope, ticketsUnblockedBy, umbrellaProgress, validateProject, withProjectLock, writeConfig, writeIssue, writeIssueUnlocked, writeRoadmap, writeRoadmapUnlocked, writeTicket, writeTicketUnlocked };
+export { type Blocker, BlockerSchema, CURRENT_SCHEMA_VERSION, type Config, ConfigSchema, DATE_REGEX, DateSchema, ERROR_CODES, type ErrorCode, type ErrorEnvelope, ExitCode, type ExitCodeValue, type Features, FeaturesSchema, INTEGRITY_WARNING_TYPES, ISSUE_ID_REGEX, ISSUE_SEVERITIES, ISSUE_STATUSES, type InitOptions, type InitResult, type Issue, IssueIdSchema, IssueSchema, type IssueSeverity, type IssueStatus, type LoadOptions, type LoadResult, type LoadWarning, type LoadWarningType, type NextTicketAllBlocked, type NextTicketAllComplete, type NextTicketEmpty, type NextTicketOutcome, type NextTicketResult, OUTPUT_FORMATS, type OutputFormat, type PartialEnvelope, type Phase, PhaseSchema, type PhaseStatus, type PhaseWithStatus, ProjectLoaderError, ProjectState, type RecapResult, type Roadmap, RoadmapSchema, type SnapshotDiff, type SnapshotV1, SnapshotV1Schema, type SuccessEnvelope, TICKET_ID_REGEX, TICKET_STATUSES, TICKET_TYPES, type Ticket, TicketIdSchema, TicketSchema, type TicketStatus, type TicketType, type UmbrellaProgress, type UnblockImpact, type ValidationFinding, type ValidationLevel, type ValidationResult, type WithProjectLockOptions, atomicWrite, blockedTickets, buildRecap, currentPhase, deleteIssue, deleteTicket, diffStates, discoverProjectRoot, errorEnvelope, escapeMarkdownInline, extractHandoverDate, fencedBlock, formatBlockedTickets, formatBlockerList, formatError, formatExport, formatHandoverContent, formatHandoverCreateResult, formatHandoverList, formatInitResult, formatIssue, formatIssueList, formatNextTicketOutcome, formatPhaseList, formatPhaseTickets, formatRecap, formatSnapshotResult, formatStatus, formatTicket, formatTicketList, formatValidation, guardPath, initProject, isBlockerCleared, listHandovers, loadLatestSnapshot, loadProject, mergeValidation, nextIssueID, nextOrder, nextTicket, nextTicketID, partialEnvelope, phasesWithStatus, readHandover, runTransaction, runTransactionUnlocked, saveSnapshot, serializeJSON, sortKeysDeep, successEnvelope, ticketsUnblockedBy, umbrellaProgress, validateProject, withProjectLock, writeConfig, writeIssue, writeIssueUnlocked, writeRoadmap, writeRoadmapUnlocked, writeTicket, writeTicketUnlocked };

package/dist/index.js

@@ -358,6 +358,7 @@ import { readdir, readFile } from "fs/promises";
 import { existsSync } from "fs";
 import { join, relative, extname } from "path";
 var HANDOVER_DATE_REGEX = /^\d{4}-\d{2}-\d{2}/;
+var HANDOVER_SEQ_REGEX = /^(\d{4}-\d{2}-\d{2})-(\d{2})-/;
 async function listHandovers(handoversDir, root, warnings) {
   if (!existsSync(handoversDir)) return [];
   let entries;
@@ -387,7 +388,16 @@ async function listHandovers(handoversDir, root, warnings) {
       });
     }
   }
-  conforming.sort((a, b) => b.localeCompare(a));
+  conforming.sort((a, b) => {
+    const dateA = a.slice(0, 10);
+    const dateB = b.slice(0, 10);
+    if (dateA !== dateB) return dateB.localeCompare(dateA);
+    const seqA = a.match(HANDOVER_SEQ_REGEX);
+    const seqB = b.match(HANDOVER_SEQ_REGEX);
+    if (seqA && !seqB) return -1;
+    if (!seqA && seqB) return 1;
+    return b.localeCompare(a);
+  });
   return [...conforming, ...nonConforming];
 }
 async function readHandover(handoversDir, filename) {
@@ -961,30 +971,43 @@ async function withLock(wrapDir, fn) {
 }
 
 // src/core/project-root-discovery.ts
-import { existsSync as existsSync3 } from "fs";
+import { existsSync as existsSync3, accessSync, constants } from "fs";
 import { resolve as resolve2, dirname as dirname2, join as join3 } from "path";
 var ENV_VAR = "CLAUDESTORY_PROJECT_ROOT";
+var STORY_DIR = ".story";
 var CONFIG_PATH = ".story/config.json";
 function discoverProjectRoot(startDir) {
   const envRoot = process.env[ENV_VAR];
   if (envRoot) {
     const resolved = resolve2(envRoot);
-    if (existsSync3(join3(resolved, CONFIG_PATH))) {
-      return resolved;
-    }
-    return null;
+    return checkRoot(resolved);
   }
   let current = resolve2(startDir ?? process.cwd());
   for (; ; ) {
-    if (existsSync3(join3(current, CONFIG_PATH))) {
-      return current;
-    }
+    const result = checkRoot(current);
+    if (result) return result;
     const parent = dirname2(current);
     if (parent === current) break;
     current = parent;
   }
   return null;
 }
+function checkRoot(candidate) {
+  if (existsSync3(join3(candidate, CONFIG_PATH))) {
+    return candidate;
+  }
+  if (existsSync3(join3(candidate, STORY_DIR))) {
+    try {
+      accessSync(join3(candidate, STORY_DIR), constants.R_OK);
+    } catch {
+      throw new ProjectLoaderError(
+        "io_error",
+        `Permission denied: cannot read .story/ in ${candidate}`
+      );
+    }
+  }
+  return null;
+}
 
 // src/core/queries.ts
 function nextTicket(state) {
@@ -1974,6 +1997,12 @@ function formatHandoverContent(filename, content, format) {
   }
   return content;
 }
+function formatHandoverCreateResult(filename, format) {
+  if (format === "json") {
+    return JSON.stringify(successEnvelope({ filename }), null, 2);
+  }
+  return `Created handover: ${filename}`;
+}
 function formatSnapshotResult(result, format) {
   if (format === "json") {
     return JSON.stringify(successEnvelope(result), null, 2);
@@ -2298,6 +2327,7 @@ export {
   formatError,
   formatExport,
   formatHandoverContent,
+  formatHandoverCreateResult,
   formatHandoverList,
   formatInitResult,
   formatIssue,

package/dist/mcp.js

@@ -2,39 +2,70 @@
 
 // src/mcp/index.ts
 import { realpathSync, existsSync as existsSync5 } from "fs";
-import { resolve as resolve6, join as join7, isAbsolute } from "path";
+import { resolve as resolve7, join as join8, isAbsolute } from "path";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
 // src/core/project-root-discovery.ts
-import { existsSync } from "fs";
+import { existsSync, accessSync, constants } from "fs";
 import { resolve, dirname, join } from "path";
+
+// src/core/errors.ts
+var CURRENT_SCHEMA_VERSION = 1;
+var ProjectLoaderError = class extends Error {
+  constructor(code, message, cause) {
+    super(message);
+    this.code = code;
+    this.cause = cause;
+  }
+  name = "ProjectLoaderError";
+};
+var INTEGRITY_WARNING_TYPES = [
+  "parse_error",
+  "schema_error",
+  "duplicate_id"
+];
+
+// src/core/project-root-discovery.ts
 var ENV_VAR = "CLAUDESTORY_PROJECT_ROOT";
+var STORY_DIR = ".story";
 var CONFIG_PATH = ".story/config.json";
 function discoverProjectRoot(startDir) {
   const envRoot = process.env[ENV_VAR];
   if (envRoot) {
     const resolved = resolve(envRoot);
-    if (existsSync(join(resolved, CONFIG_PATH))) {
-      return resolved;
-    }
-    return null;
+    return checkRoot(resolved);
   }
   let current = resolve(startDir ?? process.cwd());
   for (; ; ) {
-    if (existsSync(join(current, CONFIG_PATH))) {
-      return current;
-    }
+    const result = checkRoot(current);
+    if (result) return result;
     const parent = dirname(current);
     if (parent === current) break;
     current = parent;
   }
   return null;
 }
+function checkRoot(candidate) {
+  if (existsSync(join(candidate, CONFIG_PATH))) {
+    return candidate;
+  }
+  if (existsSync(join(candidate, STORY_DIR))) {
+    try {
+      accessSync(join(candidate, STORY_DIR), constants.R_OK);
+    } catch {
+      throw new ProjectLoaderError(
+        "io_error",
+        `Permission denied: cannot read .story/ in ${candidate}`
+      );
+    }
+  }
+  return null;
+}
 
 // src/mcp/tools.ts
 import { z as z7 } from "zod";
-import { join as join6 } from "path";
+import { join as join7 } from "path";
 
 // src/core/project-loader.ts
 import {
@@ -365,27 +396,12 @@ var ProjectState = class _ProjectState {
   }
 };
 
-// src/core/errors.ts
-var CURRENT_SCHEMA_VERSION = 1;
-var ProjectLoaderError = class extends Error {
-  constructor(code, message, cause) {
-    super(message);
-    this.code = code;
-    this.cause = cause;
-  }
-  name = "ProjectLoaderError";
-};
-var INTEGRITY_WARNING_TYPES = [
-  "parse_error",
-  "schema_error",
-  "duplicate_id"
-];
-
 // src/core/handover-parser.ts
 import { readdir, readFile } from "fs/promises";
 import { existsSync as existsSync2 } from "fs";
 import { join as join2, relative, extname } from "path";
 var HANDOVER_DATE_REGEX = /^\d{4}-\d{2}-\d{2}/;
+var HANDOVER_SEQ_REGEX = /^(\d{4}-\d{2}-\d{2})-(\d{2})-/;
 async function listHandovers(handoversDir, root, warnings) {
   if (!existsSync2(handoversDir)) return [];
   let entries;
@@ -415,7 +431,16 @@ async function listHandovers(handoversDir, root, warnings) {
       });
     }
   }
-  conforming.sort((a, b) => b.localeCompare(a));
+  conforming.sort((a, b) => {
+    const dateA = a.slice(0, 10);
+    const dateB = b.slice(0, 10);
+    if (dateA !== dateB) return dateB.localeCompare(dateA);
+    const seqA = a.match(HANDOVER_SEQ_REGEX);
+    const seqB = b.match(HANDOVER_SEQ_REGEX);
+    if (seqA && !seqB) return -1;
+    if (!seqA && seqB) return 1;
+    return b.localeCompare(a);
+  });
   return [...conforming, ...nonConforming];
 }
 async function readHandover(handoversDir, filename) {
@@ -778,6 +803,13 @@ var CliValidationError = class extends Error {
     this.name = "CliValidationError";
   }
 };
+function todayISO() {
+  const d = /* @__PURE__ */ new Date();
+  const y = d.getFullYear();
+  const m = String(d.getMonth() + 1).padStart(2, "0");
+  const day = String(d.getDate()).padStart(2, "0");
+  return `${y}-${m}-${day}`;
+}
 async function parseHandoverFilename(raw, handoversDir) {
   if (raw.includes("/") || raw.includes("\\") || raw.includes("..") || raw.includes("\0")) {
     throw new CliValidationError(
@@ -1201,6 +1233,12 @@ function formatHandoverContent(filename, content, format) {
   }
   return content;
 }
+function formatHandoverCreateResult(filename, format) {
+  if (format === "json") {
+    return JSON.stringify(successEnvelope({ filename }), null, 2);
+  }
+  return `Created handover: ${filename}`;
+}
 function formatSnapshotResult(result, format) {
   if (format === "json") {
     return JSON.stringify(successEnvelope(result), null, 2);
@@ -1740,6 +1778,8 @@ function handleValidate(ctx) {
 }
 
 // src/cli/commands/handover.ts
+import { mkdir } from "fs/promises";
+import { join as join4, resolve as resolve4 } from "path";
 function handleHandoverList(ctx) {
   return { output: formatHandoverList(ctx.state.handoverFilenames, ctx.format) };
 }
@@ -1791,6 +1831,59 @@ async function handleHandoverGet(filename, ctx) {
     };
   }
 }
+function normalizeSlug(raw) {
+  let slug = raw.trim().toLowerCase().replace(/\s+/g, "-").replace(/[^a-z0-9-]/g, "").replace(/-+/g, "-").replace(/^-|-$/g, "");
+  if (slug.length > 60) slug = slug.slice(0, 60).replace(/-$/, "");
+  if (!slug) {
+    throw new CliValidationError(
+      "invalid_input",
+      `Slug is empty after normalization: "${raw}"`
+    );
+  }
+  return slug;
+}
+async function handleHandoverCreate(content, slugRaw, format, root) {
+  if (!content.trim()) {
+    throw new CliValidationError("invalid_input", "Handover content is empty");
+  }
+  const slug = normalizeSlug(slugRaw);
+  const date = todayISO();
+  let filename;
+  await withProjectLock(root, { strict: false }, async () => {
+    const absRoot = resolve4(root);
+    const handoversDir = join4(absRoot, ".story", "handovers");
+    await mkdir(handoversDir, { recursive: true });
+    const wrapDir = join4(absRoot, ".story");
+    const datePrefix = `${date}-`;
+    const seqRegex = new RegExp(`^${date}-(\\d{2})-`);
+    let maxSeq = 0;
+    const { readdirSync } = await import("fs");
+    try {
+      for (const f of readdirSync(handoversDir)) {
+        const m = f.match(seqRegex);
+        if (m) {
+          const n = parseInt(m[1], 10);
+          if (n > maxSeq) maxSeq = n;
+        }
+      }
+    } catch {
+    }
+    const nextSeq = maxSeq + 1;
+    if (nextSeq > 99) {
+      throw new CliValidationError(
+        "conflict",
+        `Too many handovers for ${date}; limit is 99 per day`
+      );
+    }
+    const candidate = `${date}-${String(nextSeq).padStart(2, "0")}-${slug}.md`;
+    const candidatePath = join4(handoversDir, candidate);
+    await parseHandoverFilename(candidate, handoversDir);
+    await guardPath(candidatePath, wrapDir);
+    await atomicWrite(candidatePath, content);
+    filename = candidate;
+  });
+  return { output: formatHandoverCreateResult(filename, format) };
+}
 
 // src/cli/commands/blocker.ts
 function handleBlockerList(ctx) {
@@ -1883,9 +1976,9 @@ function handleIssueGet(id, ctx) {
 }
 
 // src/core/snapshot.ts
-import { readdir as readdir3, readFile as readFile3, mkdir, unlink as unlink2 } from "fs/promises";
+import { readdir as readdir3, readFile as readFile3, mkdir as mkdir2, unlink as unlink2 } from "fs/promises";
 import { existsSync as existsSync4 } from "fs";
-import { join as join4, resolve as resolve4 } from "path";
+import { join as join5, resolve as resolve5 } from "path";
 import { z as z6 } from "zod";
 var LoadWarningSchema = z6.object({
   type: z6.string(),
@@ -1904,9 +1997,9 @@ var SnapshotV1Schema = z6.object({
 });
 var MAX_SNAPSHOTS = 20;
 async function saveSnapshot(root, loadResult) {
-  const absRoot = resolve4(root);
-  const snapshotsDir = join4(absRoot, ".story", "snapshots");
-  await mkdir(snapshotsDir, { recursive: true });
+  const absRoot = resolve5(root);
+  const snapshotsDir = join5(absRoot, ".story", "snapshots");
+  await mkdir2(snapshotsDir, { recursive: true });
   const { state, warnings } = loadResult;
   const now = /* @__PURE__ */ new Date();
   const filename = formatSnapshotFilename(now);
@@ -1927,8 +2020,8 @@ async function saveSnapshot(root, loadResult) {
     } : {}
   };
   const json = JSON.stringify(snapshot, null, 2) + "\n";
-  const targetPath = join4(snapshotsDir, filename);
-  const wrapDir = join4(absRoot, ".story");
+  const targetPath = join5(snapshotsDir, filename);
+  const wrapDir = join5(absRoot, ".story");
   await guardPath(targetPath, wrapDir);
   await atomicWrite(targetPath, json);
   const pruned = await pruneSnapshots(snapshotsDir);
@@ -1936,13 +2029,13 @@ async function saveSnapshot(root, loadResult) {
   return { filename, retained: entries.length, pruned };
 }
 async function loadLatestSnapshot(root) {
-  const snapshotsDir = join4(resolve4(root), ".story", "snapshots");
+  const snapshotsDir = join5(resolve5(root), ".story", "snapshots");
   if (!existsSync4(snapshotsDir)) return null;
   const files = await listSnapshotFiles(snapshotsDir);
   if (files.length === 0) return null;
   for (const filename of files) {
     try {
-      const content = await readFile3(join4(snapshotsDir, filename), "utf-8");
+      const content = await readFile3(join5(snapshotsDir, filename), "utf-8");
       const parsed = JSON.parse(content);
       const snapshot = SnapshotV1Schema.parse(parsed);
       return { snapshot, filename };
@@ -2103,7 +2196,7 @@ async function pruneSnapshots(dir) {
   const toRemove = files.slice(MAX_SNAPSHOTS);
   for (const f of toRemove) {
     try {
-      await unlink2(join4(dir, f));
+      await unlink2(join5(dir, f));
     } catch {
     }
   }
@@ -2141,7 +2234,7 @@ function handleExport(ctx, mode, phaseId) {
 }
 
 // src/cli/commands/phase.ts
-import { join as join5, resolve as resolve5 } from "path";
+import { join as join6, resolve as resolve6 } from "path";
 function handlePhaseList(ctx) {
   return { output: formatPhaseList(ctx.state, ctx.format) };
 }
@@ -2200,7 +2293,7 @@ function formatMcpError(code, message) {
 async function runMcpReadTool(pinnedRoot, handler) {
   try {
     const { state, warnings } = await loadProject(pinnedRoot);
-    const handoversDir = join6(pinnedRoot, ".story", "handovers");
+    const handoversDir = join7(pinnedRoot, ".story", "handovers");
     const ctx = { state, warnings, root: pinnedRoot, handoversDir, format: "md" };
     const result = await handler(ctx);
     if (result.errorCode && INFRASTRUCTURE_ERROR_CODES.includes(result.errorCode)) {
@@ -2375,12 +2468,30 @@ function registerAllTools(server, pinnedRoot) {
     const phaseId = args.phase ?? null;
     return runMcpReadTool(pinnedRoot, (ctx) => handleExport(ctx, mode, phaseId));
   });
+  server.registerTool("claudestory_handover_create", {
+    description: "Create a handover document from markdown content",
+    inputSchema: {
+      content: z7.string().describe("Markdown content of the handover"),
+      slug: z7.string().optional().describe("Slug for filename (e.g. phase5b-wrapup). Default: session")
+    }
+  }, (args) => {
+    if (!args.content?.trim()) {
+      return Promise.resolve({
+        content: [{ type: "text", text: formatMcpError("invalid_input", "Handover content is empty") }],
+        isError: true
+      });
+    }
+    return runMcpWriteTool(
+      pinnedRoot,
+      (root) => handleHandoverCreate(args.content, args.slug ?? "session", "md", root)
+    );
+  });
 }
 
 // src/mcp/index.ts
 var ENV_VAR2 = "CLAUDESTORY_PROJECT_ROOT";
 var CONFIG_PATH2 = ".story/config.json";
-var version = "0.1.4";
+var version = "0.1.6";
 function pinProjectRoot() {
   const envRoot = process.env[ENV_VAR2];
   if (envRoot) {
@@ -2389,7 +2500,7 @@ function pinProjectRoot() {
 `);
       process.exit(1);
     }
-    const resolved = resolve6(envRoot);
+    const resolved = resolve7(envRoot);
     let canonical;
     try {
       canonical = realpathSync(resolved);
@@ -2398,7 +2509,7 @@ function pinProjectRoot() {
 `);
       process.exit(1);
     }
-    if (!existsSync5(join7(canonical, CONFIG_PATH2))) {
+    if (!existsSync5(join8(canonical, CONFIG_PATH2))) {
       process.stderr.write(`Error: No .story/config.json at ${canonical}
 `);
       process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anthropologies/claudestory",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "type": "module",
   "exports": {
     ".": {