@macroscope/cli 0.0.0 → 0.2.0

package/dist/core/index.d.ts

@@ -1,8 +1,9 @@
-import { H as Handler, B as Block } from '../index-BTDioymD.js';
-export { a as BlockManifest, b as BuildResult, R as RenderResult, T as TestResult, V as VERSION, i as isHandler } from '../index-BTDioymD.js';
+import { H as Handler, B as Block } from '../version-BTDioymD.js';
+export { a as BlockManifest, b as BuildResult, R as RenderResult, T as TestResult, V as VERSION, i as isHandler } from '../version-BTDioymD.js';
 import * as zod from 'zod';
 import { z } from 'zod';
-import { BlockManifest } from '@macroscope/contracts';
+import { BlockManifest, UploadPayload } from '@macroscope/contracts';
+import ts from 'typescript';
 
 declare const manifestSchema: zod.ZodObject<{
     kind: zod.ZodString;
@@ -106,9 +107,23 @@ interface BlueprintLoadResult {
  */
 declare function loadBlueprints(project: Project): Promise<BlueprintLoadResult>;
 
+interface ResolvedPaths {
+    source?: string;
+    docs?: string;
+    preview?: string;
+    tests?: string[];
+}
 interface ScannedBlock extends Block {
     /** SHA-256 over the manifest text. Used later by the index for change detection. */
     contentHash: string;
+    /**
+     * Absolute paths to manifest-referenced files, when present and inside the project.
+     * If `manifest.source` is set but the file is missing or outside the project,
+     * `resolvedPaths.source` is absent and a corresponding `io` or `validation`
+     * ScanError is in `errors[]`. T5 (extractor) should treat a missing
+     * `resolvedPaths.source` as a no-op, not an error.
+     */
+    resolvedPaths?: ResolvedPaths;
 }
 interface ScanError {
     file: string;
@@ -122,4 +137,76 @@ interface ScanResult {
 }
 declare function scan(project: Project): Promise<ScanResult>;
 
-export { Block, type BlueprintLoadCause, type BlueprintLoadError, type BlueprintLoadResult, Handler, type HandlerCapability, type LoadedBlueprint, type Manifest, type Project, type ProjectConfig, ProjectNotFoundError, type ScanError, type ScanResult, type ScannedBlock, findProject, loadBlueprints, manifestSchema, projectConfigSchema, scan };
+interface ExtractorOptions {
+    /** Cap on README excerpt characters. Default 500. */
+    readmeExcerptMax?: number;
+    /** Test seam — inject a TS Program factory. Defaults to the real ts.createProgram. */
+    programFactory?: (sourceFiles: string[]) => ts.Program;
+}
+interface ExtractionError {
+    blockId: string;
+    kind: 'parse' | 'io' | 'symbol';
+    message: string;
+}
+interface ExtractionResult {
+    /** One payload per block that had a valid `kind` (the only required manifest field). */
+    payloads: UploadPayload[];
+    /** Errors collected during extraction. NEVER thrown — bad blocks are skipped. */
+    errors: ExtractionError[];
+}
+declare function extractAll(blocks: ScannedBlock[], opts?: ExtractorOptions): Promise<ExtractionResult>;
+/**
+ * Turn raw markdown/text into a bounded excerpt safe for embedding similarity:
+ * collapse whitespace, strip the markdown formatting that confuses semantic search
+ * (`#`, `*`, backticks), and truncate at a word boundary.
+ */
+declare function formatReadmeExcerpt(raw: string, max: number): string;
+
+/**
+ * Deterministic SHA-256 over the canonical-JSON serialisation of the payload.
+ * Returns 64-character lowercase hex.
+ */
+declare function hashPayload(payload: UploadPayload): string;
+interface HasherOptions {
+    /** Override the workspace root for tests. Defaults to `process.cwd()`. */
+    workspaceRoot?: string;
+}
+interface CacheEntry {
+    /** SHA-256 hex of the canonical-JSON serialisation of the UploadPayload. */
+    hash: string;
+    /** Max(mtime ms) of the block's manifest + source + docs at hash time. */
+    mtime: number;
+}
+type HashCache = Record<string, CacheEntry>;
+/**
+ * Load the cache from disk. NEVER throws: missing file or malformed JSON
+ * return `{}` so the watcher can recover by re-hashing everything. Transparently
+ * handles both the wrapped `{ schemaVersion, entries }` shape and the legacy
+ * flat shape, returning entries either way.
+ */
+declare function loadHashCache(opts?: HasherOptions): Promise<HashCache>;
+/**
+ * Atomically write the cache to disk: write to a sibling `.tmp` file then
+ * rename. Same-directory rename is atomic on POSIX filesystems. Throws on
+ * real I/O failure — callers (watcher loop) decide whether to surface or
+ * swallow the error.
+ *
+ * The on-disk shape is the wrapped envelope (`schemaVersion` + `entries`);
+ * `schemaVersion` defaults to the current `SCHEMA_VERSION` from
+ * `@macroscope/contracts` so T14's existing callsites transparently persist it.
+ */
+declare function saveHashCache(cache: HashCache, opts?: HasherOptions & {
+    schemaVersion?: number;
+}): Promise<void>;
+/**
+ * Return the subset of blocks whose manifest, source, or docs files have an
+ * mtime strictly greater than the cached entry's recorded mtime. Blocks
+ * with no cache entry are always returned (first-time extraction needs them).
+ *
+ * Missing files (e.g. deleted between scan and stat) are treated as "changed"
+ * — safer to re-process than silently drop. The watcher reconciles deletions
+ * separately via "in cache but not in scan" diffing.
+ */
+declare function filterChangedBlocks(blocks: ScannedBlock[], cache: HashCache): Promise<ScannedBlock[]>;
+
+export { Block, type BlueprintLoadCause, type BlueprintLoadError, type BlueprintLoadResult, type CacheEntry, type ExtractionError, type ExtractionResult, type ExtractorOptions, Handler, type HandlerCapability, type HashCache, type HasherOptions, type LoadedBlueprint, type Manifest, type Project, type ProjectConfig, ProjectNotFoundError, type ResolvedPaths, type ScanError, type ScanResult, type ScannedBlock, extractAll, filterChangedBlocks, findProject, formatReadmeExcerpt, hashPayload, loadBlueprints, loadHashCache, manifestSchema, projectConfigSchema, saveHashCache, scan };

package/dist/core/index.js

@@ -7,6 +7,30 @@ import { z as z2 } from "zod";
 import { z as z3 } from "zod";
 import { z as z4 } from "zod";
 import { z as z5 } from "zod";
+import { z as z6 } from "zod";
+var SCHEMA_VERSION = 1;
+var FILESYSTEM_LAYOUT = {
+  user: {
+    /** `~/.macroscope/` */
+    rootDir: ".macroscope",
+    /** `~/.macroscope/credentials` — OAuth token store, mode 0600. */
+    credentialsFile: ".macroscope/credentials",
+    /** `~/.macroscope/machine-id` — stable per-install identifier. */
+    machineIdFile: ".macroscope/machine-id"
+  },
+  project: {
+    /** `<project>/.macroscope/` */
+    rootDir: ".macroscope",
+    /** `<project>/.macroscope/blueprints/` — one folder per kind. */
+    blueprintsDir: ".macroscope/blueprints",
+    /** `<project>/.macroscope/cache/` */
+    cacheDir: ".macroscope/cache",
+    /** `<project>/.macroscope/cache/hashes.json` — content-hash cache used by catch-up scan. */
+    hashesFile: ".macroscope/cache/hashes.json",
+    /** `<project>/.macroscope/cache/queue.json` — watcher push queue, survives restart. */
+    queueFile: ".macroscope/cache/queue.json"
+  }
+};
 var BlockManifestSchema = z.object({
   /** Must reference a registered blueprint's `kind`. */
   kind: z.string().min(1),
@@ -126,6 +150,23 @@ var ErrorEnvelopeSchema = z5.object({
     requestId: z5.string().optional()
   })
 });
+var ProviderSchema = z6.enum(["github", "gitlab"]);
+var OAuthCredentialsSchema = z6.object({
+  provider: ProviderSchema,
+  accessToken: z6.string().min(1),
+  refreshToken: z6.string().min(1).optional(),
+  /** Unix epoch milliseconds at which `accessToken` expires. */
+  expiresAt: z6.number().int().nonnegative().optional(),
+  /** Provider-side user id (e.g. GitHub `id`, GitLab `id`). Optional — useful
+   *  for UI display ("logged in as alexspdlr on github") and for the CLI to
+   *  short-circuit redundant `/user` lookups. */
+  providerUserId: z6.string().min(1).optional()
+});
+var UserContextSchema = z6.object({
+  userId: z6.string().min(1),
+  indexName: z6.string().min(1),
+  provider: ProviderSchema
+});
 
 // src/core/manifest.ts
 var manifestSchema = BlockManifestSchema;
@@ -190,10 +231,10 @@ import { existsSync } from "fs";
 import { readFile } from "fs/promises";
 import { dirname, join, resolve } from "path";
 import { parse as parseYaml } from "yaml";
-import { z as z6 } from "zod";
-var projectConfigSchema = z6.object({
-  scanRoots: z6.array(z6.string()).default(["."]),
-  ignore: z6.array(z6.string()).default(["node_modules", ".git", "dist", ".macroscope"])
+import { z as z7 } from "zod";
+var projectConfigSchema = z7.object({
+  scanRoots: z7.array(z7.string()).default(["."]),
+  ignore: z7.array(z7.string()).default(["node_modules", ".git", "dist", ".macroscope"])
 });
 var ProjectNotFoundError = class extends Error {
   constructor(startedFrom) {
@@ -361,7 +402,7 @@ function extractDefault(mod) {
 import { createHash } from "crypto";
 import { existsSync as existsSync3 } from "fs";
 import { readFile as readFile2, readdir as readdir2 } from "fs/promises";
-import { dirname as dirname2, join as join3, relative, sep } from "path";
+import { dirname as dirname2, join as join3, relative, resolve as resolve2, sep } from "path";
 import { parse as parseYaml2 } from "yaml";
 async function scan(project) {
   const blocks = [];
@@ -374,6 +415,7 @@ async function scan(project) {
     for await (const manifestPath of findManifests(start, ignore)) {
       const result = await parseBlock(manifestPath, project.root);
       if (result.kind === "ok") {
+        errors.push(...result.errors);
         if (seenIds.has(result.block.id)) {
           errors.push({
             file: manifestPath,
@@ -407,6 +449,7 @@ async function* findManifests(dir, ignore) {
   }
   for (const entry of entries) {
     if (!entry.isDirectory()) continue;
+    if (entry.isSymbolicLink()) continue;
     if (ignore.has(entry.name)) continue;
     yield* findManifests(join3(dir, entry.name), ignore);
   }
@@ -456,11 +499,85 @@ async function parseBlock(manifestPath, projectRoot) {
   const defaultId = toPosix(relative(projectRoot, blockDir));
   const id = manifest.id ?? defaultId;
   const contentHash = createHash("sha256").update(raw).digest("hex");
+  const fileErrors = [];
+  const resolvedPaths = resolveManifestPaths(
+    manifest,
+    blockDir,
+    projectRoot,
+    manifestPath,
+    fileErrors
+  );
   return {
     kind: "ok",
-    block: { id, path: blockDir, manifest, contentHash }
+    block: { id, path: blockDir, manifest, contentHash, resolvedPaths },
+    errors: fileErrors
   };
 }
+var FILE_FIELDS = ["source", "docs", "preview"];
+function resolveManifestPaths(manifest, blockDir, projectRoot, manifestPath, errors) {
+  const testsRaw = manifest.tests;
+  const testsArray = testsRaw == null ? void 0 : typeof testsRaw === "string" ? [testsRaw] : testsRaw;
+  const hasAnyField = FILE_FIELDS.some((f) => manifest[f] != null) || testsArray != null;
+  if (!hasAnyField) return void 0;
+  const resolved = {};
+  for (const field of FILE_FIELDS) {
+    const value = manifest[field];
+    if (value == null) continue;
+    const abs = resolve2(blockDir, value);
+    if (!isInsideProject(abs, projectRoot)) {
+      errors.push({
+        file: manifestPath,
+        kind: "validation",
+        field,
+        message: `Field \`${field}\` in ${manifestPath} resolves to ${abs}, which is outside the project root ${projectRoot}.`
+      });
+      continue;
+    }
+    if (!existsSync3(abs)) {
+      errors.push({
+        file: manifestPath,
+        kind: "io",
+        field,
+        message: `Field \`${field}\` in ${manifestPath} references ${abs}, which does not exist.`
+      });
+      continue;
+    }
+    resolved[field] = abs;
+  }
+  if (testsArray) {
+    const resolvedTests = [];
+    for (const t of testsArray) {
+      const abs = resolve2(blockDir, t);
+      if (!isInsideProject(abs, projectRoot)) {
+        errors.push({
+          file: manifestPath,
+          kind: "validation",
+          field: "tests",
+          message: `Field \`tests\` in ${manifestPath} resolves to ${abs}, which is outside the project root ${projectRoot}.`
+        });
+        continue;
+      }
+      if (!existsSync3(abs)) {
+        errors.push({
+          file: manifestPath,
+          kind: "io",
+          field: "tests",
+          message: `Field \`tests\` in ${manifestPath} references ${abs}, which does not exist.`
+        });
+        continue;
+      }
+      resolvedTests.push(abs);
+    }
+    if (resolvedTests.length > 0) {
+      resolved.tests = resolvedTests;
+    }
+  }
+  return Object.keys(resolved).length > 0 ? resolved : void 0;
+}
+function isInsideProject(absPath, projectRoot) {
+  const normalized = resolve2(absPath);
+  return normalized === projectRoot || normalized.startsWith(projectRoot + sep);
+}
 function firstZodIssue(err) {
   const issue = err.issues[0];
   if (!issue) return { fieldPath: "(root)", message: "unknown validation error" };
@@ -470,14 +587,396 @@ function firstZodIssue(err) {
 function toPosix(p) {
   return p.split(sep).join("/");
 }
+
+// src/core/extractor.ts
+import { readFile as readFile3 } from "fs/promises";
+import ts from "typescript";
+var DEFAULT_README_EXCERPT_MAX = 500;
+var TS_EXTENSIONS = /* @__PURE__ */ new Set([".ts", ".tsx", ".mts", ".cts"]);
+var DEFAULT_COMPILER_OPTIONS = {
+  target: ts.ScriptTarget.ES2022,
+  module: ts.ModuleKind.ESNext,
+  moduleResolution: ts.ModuleResolutionKind.Bundler,
+  jsx: ts.JsxEmit.ReactJSX,
+  allowJs: false,
+  noEmit: true,
+  skipLibCheck: true,
+  esModuleInterop: true,
+  allowSyntheticDefaultImports: true,
+  strict: false,
+  isolatedModules: true
+};
+function defaultProgramFactory(rootFiles) {
+  return ts.createProgram(rootFiles, DEFAULT_COMPILER_OPTIONS);
+}
+async function extractAll(blocks, opts = {}) {
+  const readmeMax = opts.readmeExcerptMax ?? DEFAULT_README_EXCERPT_MAX;
+  const payloads = [];
+  const errors = [];
+  const sourcesToBlocks = /* @__PURE__ */ new Map();
+  for (const block of blocks) {
+    if (!block.manifest?.kind) continue;
+    const src = block.resolvedPaths?.source;
+    if (src && isTsSource(src)) {
+      sourcesToBlocks.set(src, block);
+    }
+  }
+  let program;
+  let checker;
+  if (sourcesToBlocks.size > 0) {
+    const rootFiles = Array.from(sourcesToBlocks.keys());
+    const factory = opts.programFactory ?? defaultProgramFactory;
+    program = factory(rootFiles);
+    checker = program.getTypeChecker();
+  }
+  for (const block of blocks) {
+    if (!block.manifest?.kind) continue;
+    const payload = {
+      blockId: block.id,
+      kind: block.manifest.kind,
+      symbols: []
+    };
+    const { name, description, tags } = block.manifest;
+    if (typeof name === "string") payload.name = name;
+    if (typeof description === "string") payload.description = description;
+    if (Array.isArray(tags)) payload.tags = tags;
+    const sourcePath = block.resolvedPaths?.source;
+    if (sourcePath && isTsSource(sourcePath) && program && checker) {
+      const sourceFile = program.getSourceFile(sourcePath);
+      if (!sourceFile) {
+        errors.push({
+          blockId: block.id,
+          kind: "parse",
+          message: `TS Program did not load ${sourcePath} (parse error or missing file)`
+        });
+      } else if (hasFatalSyntaxErrors(program, sourceFile)) {
+        errors.push({
+          blockId: block.id,
+          kind: "parse",
+          message: `Source file ${sourcePath} has syntax errors; skipping symbol extraction`
+        });
+      } else {
+        payload.symbols = extractSymbols(sourceFile, checker);
+      }
+    }
+    const docsPath = block.resolvedPaths?.docs;
+    if (docsPath) {
+      try {
+        const raw = await readFile3(docsPath, "utf8");
+        payload.readmeExcerpt = formatReadmeExcerpt(raw, readmeMax);
+      } catch (err) {
+        errors.push({
+          blockId: block.id,
+          kind: "io",
+          message: `Failed to read docs at ${docsPath}: ${err.message}`
+        });
+      }
+    }
+    payloads.push(payload);
+  }
+  return { payloads, errors };
+}
+function isTsSource(path) {
+  const dot = path.lastIndexOf(".");
+  if (dot < 0) return false;
+  return TS_EXTENSIONS.has(path.slice(dot).toLowerCase());
+}
+function hasFatalSyntaxErrors(program, sourceFile) {
+  const diagnostics = program.getSyntacticDiagnostics(sourceFile);
+  return diagnostics.length > 0;
+}
+function extractSymbols(sourceFile, checker) {
+  const symbols = [];
+  for (const statement of sourceFile.statements) {
+    visitTopLevel(statement, sourceFile, checker, symbols);
+  }
+  const seen = /* @__PURE__ */ new Set();
+  return symbols.filter((s) => {
+    const key = `${s.kind}\0${s.name}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+function visitTopLevel(node, sourceFile, checker, out) {
+  if (ts.isExportAssignment(node)) {
+    out.push(extractDefaultExport(node, sourceFile, checker));
+    return;
+  }
+  if (ts.isExportDeclaration(node)) {
+    extractExportDeclaration(node, sourceFile, checker, out);
+    return;
+  }
+  if (!hasExportModifier(node)) return;
+  const isDefault = hasDefaultModifier(node);
+  if (ts.isFunctionDeclaration(node)) {
+    const name = node.name?.text ?? (isDefault ? "default" : void 0);
+    if (!name) return;
+    out.push({
+      name,
+      kind: "function",
+      signature: renderFunctionSignature(node, name, sourceFile, checker)
+    });
+    return;
+  }
+  if (ts.isClassDeclaration(node)) {
+    const name = node.name?.text ?? (isDefault ? "default" : void 0);
+    if (!name) return;
+    out.push({ name, kind: "class", signature: `class ${name}` });
+    return;
+  }
+  if (ts.isInterfaceDeclaration(node)) {
+    out.push({
+      name: node.name.text,
+      kind: "interface",
+      signature: oneLineDeclaration(node, sourceFile, `interface ${node.name.text}`)
+    });
+    return;
+  }
+  if (ts.isTypeAliasDeclaration(node)) {
+    out.push({
+      name: node.name.text,
+      kind: "type",
+      signature: oneLineDeclaration(node, sourceFile, `type ${node.name.text}`)
+    });
+    return;
+  }
+  if (ts.isEnumDeclaration(node)) {
+    out.push({ name: node.name.text, kind: "enum", signature: `enum ${node.name.text}` });
+    return;
+  }
+  if (ts.isVariableStatement(node)) {
+    for (const decl of node.declarationList.declarations) {
+      if (!ts.isIdentifier(decl.name)) continue;
+      const name = decl.name.text;
+      out.push({
+        name,
+        kind: "const",
+        signature: renderVariableSignature(decl, name, checker)
+      });
+    }
+    return;
+  }
+}
+function extractDefaultExport(node, sourceFile, checker) {
+  const expr = node.expression;
+  if (ts.isIdentifier(expr)) {
+    const sym = checker.getSymbolAtLocation(expr);
+    const type = sym ? checker.getTypeOfSymbolAtLocation(sym, expr) : void 0;
+    const signature = type ? checker.typeToString(type) : "default";
+    return { name: "default", kind: "const", signature };
+  }
+  return { name: "default", kind: "const", signature: expr.getText(sourceFile) };
+}
+function extractExportDeclaration(node, sourceFile, checker, out) {
+  if (!node.exportClause && node.moduleSpecifier) {
+    const moduleSymbol = checker.getSymbolAtLocation(node.moduleSpecifier);
+    if (moduleSymbol) {
+      for (const exp of checker.getExportsOfModule(moduleSymbol)) {
+        out.push(renderExportedSymbol(exp.name, exp, checker, sourceFile));
+      }
+    }
+    return;
+  }
+  if (node.exportClause && ts.isNamedExports(node.exportClause)) {
+    for (const spec of node.exportClause.elements) {
+      const name = spec.name.text;
+      const sym = checker.getSymbolAtLocation(spec.name);
+      out.push(renderExportedSymbol(name, sym, checker, sourceFile));
+    }
+  }
+}
+function renderExportedSymbol(name, symbol, checker, sourceFile) {
+  if (!symbol) return { name, kind: "const", signature: name };
+  const aliased = (symbol.flags & ts.SymbolFlags.Alias) !== 0 ? checker.getAliasedSymbol(symbol) : symbol;
+  const decl = aliased.declarations?.[0];
+  if (decl) {
+    if (ts.isFunctionDeclaration(decl) || ts.isMethodDeclaration(decl)) {
+      return {
+        name,
+        kind: "function",
+        signature: renderFunctionSignature(decl, name, sourceFile, checker)
+      };
+    }
+    if (ts.isClassDeclaration(decl)) return { name, kind: "class", signature: `class ${name}` };
+    if (ts.isInterfaceDeclaration(decl)) {
+      return {
+        name,
+        kind: "interface",
+        signature: oneLineDeclaration(decl, decl.getSourceFile(), `interface ${name}`)
+      };
+    }
+    if (ts.isTypeAliasDeclaration(decl)) {
+      return {
+        name,
+        kind: "type",
+        signature: oneLineDeclaration(decl, decl.getSourceFile(), `type ${name}`)
+      };
+    }
+    if (ts.isEnumDeclaration(decl)) return { name, kind: "enum", signature: `enum ${name}` };
+  }
+  const type = checker.getTypeOfSymbolAtLocation(aliased, sourceFile);
+  return { name, kind: "const", signature: checker.typeToString(type) };
+}
+function renderFunctionSignature(node, name, _sourceFile, checker) {
+  const signature = checker.getSignatureFromDeclaration(node);
+  if (!signature) return `function ${name}()`;
+  return `function ${name}${checker.signatureToString(signature)}`;
+}
+function renderVariableSignature(decl, name, checker) {
+  const type = checker.getTypeAtLocation(decl);
+  return `const ${name}: ${checker.typeToString(type)}`;
+}
+function oneLineDeclaration(node, sourceFile, fallback) {
+  try {
+    const text = node.getText(sourceFile);
+    const collapsed = text.replace(/\s+/g, " ").trim();
+    return collapsed.length > 0 ? collapsed : fallback;
+  } catch {
+    return fallback;
+  }
+}
+function hasExportModifier(node) {
+  return (ts.getCombinedModifierFlags(node) & ts.ModifierFlags.Export) !== 0;
+}
+function hasDefaultModifier(node) {
+  return (ts.getCombinedModifierFlags(node) & ts.ModifierFlags.Default) !== 0;
+}
+function formatReadmeExcerpt(raw, max) {
+  const stripped = raw.replace(/[#*`_~>]/g, "");
+  const collapsed = stripped.replace(/\s+/g, " ").trim();
+  if (collapsed.length <= max) return collapsed;
+  const slice = collapsed.slice(0, max);
+  const nextChar = collapsed.charAt(max);
+  if (nextChar === "" || /\s/.test(nextChar)) return slice;
+  const lastSpace = slice.lastIndexOf(" ");
+  if (lastSpace > 0) return slice.slice(0, lastSpace);
+  return slice;
+}
+
+// src/core/hasher.ts
+import { createHash as createHash2 } from "crypto";
+import { mkdir, readFile as readFile4, rename, stat, writeFile } from "fs/promises";
+import { dirname as dirname3, join as join4 } from "path";
+function canonicalJSON(value) {
+  return stringify(value);
+}
+function stringify(value) {
+  if (value === null) return "null";
+  if (typeof value === "string") return JSON.stringify(value.normalize("NFC"));
+  if (typeof value === "number" || typeof value === "boolean") return JSON.stringify(value);
+  if (Array.isArray(value)) {
+    const parts = value.map((v) => v === void 0 ? "null" : stringify(v));
+    return `[${parts.join(",")}]`;
+  }
+  if (typeof value === "object") {
+    const obj = value;
+    const keys = Object.keys(obj).filter((k) => obj[k] !== void 0).sort();
+    const parts = keys.map((k) => `${JSON.stringify(k)}:${stringify(obj[k])}`);
+    return `{${parts.join(",")}}`;
+  }
+  throw new TypeError(`canonicalJSON: unsupported value type ${typeof value}`);
+}
+function hashPayload(payload) {
+  const canonical = canonicalJSON(payload);
+  return createHash2("sha256").update(canonical, "utf8").digest("hex");
+}
+function resolveHashesPath(opts) {
+  const root = opts?.workspaceRoot ?? process.cwd();
+  return join4(root, FILESYSTEM_LAYOUT.project.hashesFile);
+}
+async function readCacheFile(opts) {
+  const path = resolveHashesPath(opts);
+  let raw;
+  try {
+    raw = await readFile4(path, "utf8");
+  } catch (err) {
+    const code = err.code;
+    if (code !== "ENOENT") {
+      console.warn(`[macroscope] failed to read hash cache at ${path}: ${err.message}`);
+    }
+    return null;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    console.warn(`[macroscope] hash cache at ${path} is not valid JSON: ${err.message}`);
+    return null;
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    console.warn(`[macroscope] hash cache at ${path} has unexpected shape; ignoring`);
+    return null;
+  }
+  const obj = parsed;
+  if (typeof obj.schemaVersion === "number" && obj.entries && typeof obj.entries === "object" && !Array.isArray(obj.entries)) {
+    return { schemaVersion: obj.schemaVersion, entries: obj.entries };
+  }
+  return { schemaVersion: void 0, entries: obj };
+}
+async function loadHashCache(opts) {
+  const file = await readCacheFile(opts);
+  return file?.entries ?? {};
+}
+async function saveHashCache(cache, opts) {
+  const path = resolveHashesPath(opts);
+  const dir = dirname3(path);
+  await mkdir(dir, { recursive: true });
+  const tmp = `${path}.tmp`;
+  const envelope = {
+    schemaVersion: opts?.schemaVersion ?? SCHEMA_VERSION,
+    entries: cache
+  };
+  const body = `${JSON.stringify(envelope, null, 2)}
+`;
+  await writeFile(tmp, body, "utf8");
+  await rename(tmp, path);
+}
+async function filterChangedBlocks(blocks, cache) {
+  const changed = [];
+  for (const block of blocks) {
+    const cached = cache[block.id];
+    if (!cached) {
+      changed.push(block);
+      continue;
+    }
+    const maxMtime = await maxFileMtime(block);
+    if (maxMtime === void 0 || maxMtime > cached.mtime) {
+      changed.push(block);
+    }
+  }
+  return changed;
+}
+async function maxFileMtime(block) {
+  const paths = [join4(block.path, "macroscope.yaml")];
+  if (block.resolvedPaths?.source) paths.push(block.resolvedPaths.source);
+  if (block.resolvedPaths?.docs) paths.push(block.resolvedPaths.docs);
+  let max;
+  for (const p of paths) {
+    try {
+      const s = await stat(p);
+      const m = s.mtimeMs;
+      if (max === void 0 || m > max) max = m;
+    } catch {
+      return void 0;
+    }
+  }
+  return max;
+}
 export {
   ProjectNotFoundError,
   VERSION,
+  extractAll,
+  filterChangedBlocks,
   findProject,
+  formatReadmeExcerpt,
+  hashPayload,
   isHandler,
   loadBlueprints,
+  loadHashCache,
   manifestSchema,
   projectConfigSchema,
+  saveHashCache,
   scan
 };
 //# sourceMappingURL=index.js.map