@karmaniverous/jeeves-meta 0.15.4 → 0.15.6

package/dist/schema/config.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Zod schema for jeeves-meta service configuration.
+ *
+ * The service config is a strict superset of the core (library-compatible) meta config.
+ *
+ * @module schema/config
+ */
+import { type MetaConfig, metaConfigSchema } from '@karmaniverous/jeeves-meta-core';
+import { z } from 'zod';
+export { type MetaConfig, metaConfigSchema };
+/** Zod schema for a single auto-seed policy rule. */
+declare const autoSeedRuleSchema: z.ZodObject<{
+    match: z.ZodString;
+    steer: z.ZodOptional<z.ZodString>;
+    crossRefs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+/** Inferred type for an auto-seed rule. */
+export type AutoSeedRule = z.infer<typeof autoSeedRuleSchema>;
+/** Zod schema for jeeves-meta service configuration (superset of MetaConfig). */
+export declare const serviceConfigSchema: z.ZodObject<{
+    watcherUrl: z.ZodURL;
+    gatewayUrl: z.ZodDefault<z.ZodURL>;
+    gatewayApiKey: z.ZodOptional<z.ZodString>;
+    architectEvery: z.ZodDefault<z.ZodNumber>;
+    depthWeight: z.ZodDefault<z.ZodNumber>;
+    maxArchive: z.ZodDefault<z.ZodNumber>;
+    maxLines: z.ZodDefault<z.ZodNumber>;
+    architectTimeout: z.ZodDefault<z.ZodNumber>;
+    builderTimeout: z.ZodDefault<z.ZodNumber>;
+    criticTimeout: z.ZodDefault<z.ZodNumber>;
+    thinking: z.ZodDefault<z.ZodString>;
+    defaultArchitect: z.ZodOptional<z.ZodString>;
+    defaultCritic: z.ZodOptional<z.ZodString>;
+    skipUnchanged: z.ZodDefault<z.ZodBoolean>;
+    metaProperty: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    metaArchiveProperty: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    port: z.ZodDefault<z.ZodNumber>;
+    schedule: z.ZodDefault<z.ZodString>;
+    reportChannel: z.ZodOptional<z.ZodString>;
+    reportTarget: z.ZodOptional<z.ZodString>;
+    serverBaseUrl: z.ZodOptional<z.ZodString>;
+    watcherHealthIntervalMs: z.ZodDefault<z.ZodNumber>;
+    logging: z.ZodDefault<z.ZodObject<{
+        level: z.ZodDefault<z.ZodString>;
+        file: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    autoSeed: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        match: z.ZodString;
+        steer: z.ZodOptional<z.ZodString>;
+        crossRefs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>>>;
+}, z.core.$strip>;
+/** Inferred type for service configuration. */
+export type ServiceConfig = z.infer<typeof serviceConfigSchema>;

package/dist/schema/error.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Re-export structured error schema from core.
+ *
+ * @module schema/error
+ */
+export { type MetaError, metaErrorSchema, } from '@karmaniverous/jeeves-meta-core';

package/dist/schema/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Re-exports for all schema modules.
+ *
+ * @module schema
+ */
+export { type AutoSeedRule, type MetaConfig, metaConfigSchema, type ServiceConfig, serviceConfigSchema, } from './config.js';
+export { type MetaError, metaErrorSchema } from './error.js';
+export { type MetaJson, metaJsonSchema, type PhaseName, phaseNames, type PhaseState, phaseStateSchema, type PhaseStatus, phaseStatuses, } from './meta.js';

package/dist/schema/meta.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Zod schema for .meta/meta.json files.
+ *
+ * Reserved properties are underscore-prefixed and engine-managed.
+ * All other keys are open schema (builder output).
+ *
+ * @module schema/meta
+ */
+import { type PhaseName, phaseNames, type PhaseState, phaseStateSchema, type PhaseStatus, phaseStatuses } from '@karmaniverous/jeeves-meta-core';
+import { z } from 'zod';
+export { type PhaseName, phaseNames, type PhaseState, phaseStateSchema, type PhaseStatus, phaseStatuses, };
+/** Zod schema for the reserved (underscore-prefixed) meta.json properties. */
+export declare const metaJsonSchema: z.ZodObject<{
+    _id: z.ZodOptional<z.ZodUUID>;
+    _steer: z.ZodOptional<z.ZodString>;
+    _crossRefs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    _architect: z.ZodOptional<z.ZodString>;
+    _builder: z.ZodOptional<z.ZodString>;
+    _critic: z.ZodOptional<z.ZodString>;
+    _generatedAt: z.ZodOptional<z.ZodISODateTime>;
+    _content: z.ZodOptional<z.ZodString>;
+    _structureHash: z.ZodOptional<z.ZodString>;
+    _synthesisCount: z.ZodOptional<z.ZodNumber>;
+    _feedback: z.ZodOptional<z.ZodString>;
+    _archived: z.ZodOptional<z.ZodBoolean>;
+    _archivedAt: z.ZodOptional<z.ZodISODateTime>;
+    _depth: z.ZodOptional<z.ZodNumber>;
+    _emphasis: z.ZodOptional<z.ZodNumber>;
+    _architectTokens: z.ZodOptional<z.ZodNumber>;
+    _builderTokens: z.ZodOptional<z.ZodNumber>;
+    _criticTokens: z.ZodOptional<z.ZodNumber>;
+    _architectTokensAvg: z.ZodOptional<z.ZodNumber>;
+    _builderTokensAvg: z.ZodOptional<z.ZodNumber>;
+    _criticTokensAvg: z.ZodOptional<z.ZodNumber>;
+    _state: z.ZodOptional<z.ZodUnknown>;
+    _error: z.ZodOptional<z.ZodObject<{
+        step: z.ZodEnum<{
+            architect: "architect";
+            builder: "builder";
+            critic: "critic";
+        }>;
+        code: z.ZodString;
+        message: z.ZodString;
+    }, z.core.$strip>>;
+    _disabled: z.ZodOptional<z.ZodBoolean>;
+    _phaseState: z.ZodOptional<z.ZodObject<{
+        architect: z.ZodEnum<{
+            fresh: "fresh";
+            stale: "stale";
+            pending: "pending";
+            running: "running";
+            failed: "failed";
+        }>;
+        builder: z.ZodEnum<{
+            fresh: "fresh";
+            stale: "stale";
+            pending: "pending";
+            running: "running";
+            failed: "failed";
+        }>;
+        critic: z.ZodEnum<{
+            fresh: "fresh";
+            stale: "stale";
+            pending: "pending";
+            running: "running";
+            failed: "failed";
+        }>;
+    }, z.core.$strip>>;
+}, z.core.$loose>;
+/** Inferred type for meta.json. */
+export type MetaJson = z.infer<typeof metaJsonSchema>;

package/dist/seed/autoSeed.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Auto-seed pass — scan for directories matching policy rules and seed them.
+ *
+ * Runs before discovery in each scheduler tick. For each auto-seed rule,
+ * walks matching directories via the watcher and creates .meta/ directories
+ * for those that don't already have one.
+ *
+ * Rules are processed in array order; last match wins for steer/crossRefs.
+ *
+ * @module seed/autoSeed
+ */
+import type { WatcherClient } from '../interfaces/index.js';
+import type { MinimalLogger } from '../logger/index.js';
+import type { AutoSeedRule } from '../schema/config.js';
+/** Result of a single auto-seed pass. */
+export interface AutoSeedResult {
+    /** Number of new metas created. */
+    seeded: number;
+    /** Paths that were seeded. */
+    paths: string[];
+}
+/**
+ * Run the auto-seed pass: apply policy rules and create missing metas.
+ *
+ * @param rules - Auto-seed policy rules from config.
+ * @param watcher - Watcher client for filesystem enumeration.
+ * @param logger - Logger for reporting seed actions.
+ * @returns Summary of what was seeded.
+ */
+export declare function autoSeedPass(rules: AutoSeedRule[], watcher: WatcherClient, logger?: MinimalLogger): Promise<AutoSeedResult>;

package/dist/seed/createMeta.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Core seed logic — create a .meta/ directory with initial meta.json.
+ *
+ * Shared between the POST /seed route handler and the auto-seed pass.
+ *
+ * @module seed/createMeta
+ */
+/** Options for creating a new meta. */
+export interface CreateMetaOptions {
+    /** Cross-references to other meta owner paths. */
+    crossRefs?: string[];
+    /** Steering prompt for the meta. */
+    steer?: string;
+}
+/** Result of creating a new meta. */
+export interface CreateMetaResult {
+    /** Absolute path to the .meta/ directory. */
+    metaDir: string;
+    /** The generated UUID. */
+    _id: string;
+}
+/**
+ * Create a .meta/ directory with an initial meta.json.
+ *
+ * Does NOT check for existing .meta/ — caller is responsible for that guard.
+ *
+ * @param ownerPath - The owner directory path.
+ * @param options - Optional cross-refs and steering prompt.
+ * @returns The meta directory path and generated ID.
+ */
+export declare function createMeta(ownerPath: string, options?: CreateMetaOptions): Promise<CreateMetaResult>;
+/**
+ * Check if a .meta/ directory already exists for an owner path.
+ *
+ * @param ownerPath - The owner directory path.
+ * @returns True if .meta/ already exists.
+ */
+export declare function metaExists(ownerPath: string): boolean;

package/dist/seed/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Seed module — create .meta/ directories with initial meta.json.
+ *
+ * @module seed
+ */
+export { autoSeedPass, type AutoSeedResult } from './autoSeed.js';
+export { createMeta, type CreateMetaOptions, type CreateMetaResult, metaExists, } from './createMeta.js';

package/dist/server.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Minimal Fastify HTTP server for jeeves-meta service.
+ *
+ * @module server
+ */
+import { type FastifyBaseLogger } from 'fastify';
+import type { Logger } from 'pino';
+import { type RouteDeps } from './routes/index.js';
+/** Options for creating the server. */
+export interface ServerOptions {
+    /** Pino logger instance. */
+    logger: Logger;
+    /** Shared route dependencies (mutable — late-bound properties like registrar are set after creation). */
+    deps: RouteDeps;
+}
+/**
+ * Create and configure the Fastify server.
+ *
+ * @param options - Server creation options.
+ * @returns Configured Fastify instance (not yet listening).
+ */
+export declare function createServer(options: ServerOptions): import("fastify").FastifyInstance<import("node:http").Server<typeof import("node:http").IncomingMessage, typeof import("node:http").ServerResponse>, import("node:http").IncomingMessage, import("node:http").ServerResponse<import("node:http").IncomingMessage>, FastifyBaseLogger, import("fastify").FastifyTypeProviderDefault> & PromiseLike<import("fastify").FastifyInstance<import("node:http").Server<typeof import("node:http").IncomingMessage, typeof import("node:http").ServerResponse>, import("node:http").IncomingMessage, import("node:http").ServerResponse<import("node:http").IncomingMessage>, FastifyBaseLogger, import("fastify").FastifyTypeProviderDefault>> & {
+    __linterBrands: "SafePromiseLike";
+};

package/dist/shutdown/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Graceful shutdown handler.
+ *
+ * On SIGTERM/SIGINT: stops scheduler, drains queue, cleans up locks.
+ *
+ * @module shutdown
+ */
+import type { Logger } from 'pino';
+import type { SynthesisQueue } from '../queue/index.js';
+import type { RouteDeps } from '../routes/index.js';
+import type { Scheduler } from '../scheduler/index.js';
+interface ShutdownDeps {
+    server: {
+        close: () => Promise<void>;
+    };
+    scheduler: Scheduler | null;
+    queue: SynthesisQueue;
+    logger: Logger;
+    routeDeps?: RouteDeps;
+    /** Optional cleanup callback (e.g., stop health check). */
+    onShutdown?: () => void;
+}
+/**
+ * Register shutdown handlers for SIGTERM and SIGINT.
+ *
+ * Flow:
+ * 1. Stop scheduler (no new ticks)
+ * 2. If synthesis in progress, release its lock
+ * 3. Close Fastify server
+ * 4. Exit
+ */
+export declare function registerShutdownHandlers(deps: ShutdownDeps): void;
+export {};

package/dist/structureHash.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Compute a structure hash from a sorted file listing.
+ *
+ * Used to detect when directory structure changes, triggering
+ * an architect re-run.
+ *
+ * @module structureHash
+ */
+/**
+ * Compute a SHA-256 hash of a sorted file listing.
+ *
+ * @param filePaths - Array of file paths in scope.
+ * @returns Hex-encoded SHA-256 hash of the sorted, newline-joined paths.
+ */
+export declare function computeStructureHash(filePaths: string[]): string;

package/dist/watcher-client/HttpWatcherClient.d.ts

@@ -0,0 +1,38 @@
+/**
+ * HTTP implementation of the WatcherClient interface.
+ *
+ * Talks to jeeves-watcher's POST /walk and POST /rules/register endpoints
+ * with retry and exponential backoff.
+ *
+ * @module watcher-client/HttpWatcherClient
+ */
+import type { InferenceRuleSpec, WatcherClient, WatcherScanRequest, WatcherScanResult } from '../interfaces/index.js';
+/** Options for creating an HttpWatcherClient. */
+export interface HttpWatcherClientOptions {
+    /** Base URL for the watcher service (e.g. "http://localhost:1936"). */
+    baseUrl: string;
+    /** Maximum retry attempts for transient failures. Default: 3. */
+    maxRetries?: number;
+    /** Base delay in ms for exponential backoff. Default: 1000. */
+    backoffBaseMs?: number;
+    /** Multiplier for backoff. Default: 4 (1s, 4s, 16s). */
+    backoffFactor?: number;
+    /** Per-request timeout in ms. Default: 10000. */
+    timeoutMs?: number;
+}
+/**
+ * HTTP-based WatcherClient implementation with retry.
+ */
+export declare class HttpWatcherClient implements WatcherClient {
+    private readonly baseUrl;
+    private readonly maxRetries;
+    private readonly backoffBaseMs;
+    private readonly backoffFactor;
+    private readonly timeoutMs;
+    constructor(options: HttpWatcherClientOptions);
+    /** POST JSON with retry. */
+    private post;
+    registerRules(source: string, rules: InferenceRuleSpec[]): Promise<void>;
+    walk(globs: string[]): Promise<string[]>;
+    scan(request: WatcherScanRequest): Promise<WatcherScanResult>;
+}

package/dist/watcher-client/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * WatcherClient implementations.
+ *
+ * @module watcher-client
+ */
+export { HttpWatcherClient, type HttpWatcherClientOptions, } from './HttpWatcherClient.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@karmaniverous/jeeves-meta",
-  "version": "0.15.4",
+  "version": "0.15.6",
   "author": "Jason Williscroft",
   "description": "Fastify HTTP service for the Jeeves Meta synthesis engine",
   "license": "BSD-3-Clause",
@@ -41,33 +41,30 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@karmaniverous/jeeves": "^0.5.9",
+    "@karmaniverous/jeeves": "^0.5.10",
+    "@karmaniverous/jeeves-meta-core": "^0.1.1",
     "commander": "^14",
     "croner": "^10",
     "fastify": "^5.8",
     "handlebars": "^4.7.9",
     "package-directory": "^8.2.0",
     "pino": "^10",
-    "zod": "^4.3"
+    "zod": "^4.4"
   },
   "devDependencies": {
-    "@commander-js/extra-typings": "^14.0.0",
-    "@dotenvx/dotenvx": "^1.59.1",
+    "@dotenvx/dotenvx": "^1.65.0",
     "@rollup/plugin-commonjs": "^29.0.2",
     "@rollup/plugin-json": "^6.1.0",
     "@rollup/plugin-node-resolve": "^16.0.3",
     "@rollup/plugin-typescript": "^12.3.0",
-    "@types/node": "^25.5.2",
-    "@vitest/coverage-v8": "^4.1.2",
-    "auto-changelog": "^2.5.0",
+    "@types/node": "^25.7.0",
+    "@vitest/coverage-v8": "^4.1.6",
     "cross-env": "^10.1.0",
-    "knip": "^5.87.0",
-    "release-it": "^19.2.4",
-    "rollup": "^4.60.1",
+    "release-it": "^20.0.1",
+    "rollup": "^4.60.3",
     "rollup-plugin-copy": "^3.5.0",
-    "rollup-plugin-dts": "^6.4.1",
     "tslib": "^2.8.1",
-    "vitest": "^4.1.2"
+    "vitest": "^4.1.6"
   },
   "scripts": {
     "build": "rimraf dist && cross-env NO_COLOR=1 rollup --config rollup.config.ts --configPlugin @rollup/plugin-typescript",
@@ -76,7 +73,7 @@
     "lint:fix": "eslint --fix .",
     "test": "vitest run",
     "typecheck": "tsc",
-    "changelog": "auto-changelog",
+    "changelog": "git-cliff -o CHANGELOG.md",
     "release": "dotenvx run -f .env.local -- release-it",
     "release:pre": "dotenvx run -f .env.local -- release-it --no-git.requireBranch --github.prerelease --preRelease"
   },
@@ -85,7 +82,7 @@
   },
   "release-it": {
     "git": {
-      "changelog": "npx auto-changelog --unreleased-only --stdout --template https://raw.githubusercontent.com/release-it/release-it/main/templates/changelog-compact.hbs",
+      "changelog": "npx git-cliff --unreleased --strip header",
       "commitMessage": "chore: release @karmaniverous/jeeves-meta v${version}",
       "tagName": "service/${version}",
       "requireBranch": "main"
@@ -100,25 +97,18 @@
         "npm run test",
         "npm run build"
       ],
-      "before:npm:release": [
-        "npx auto-changelog -p",
-        "git add -A"
-      ],
       "after:release": [
         "git switch -c release/service/${version}",
         "git push -u origin release/service/${version}",
         "git switch ${branchName}"
+      ],
+      "before:npm:release": [
+        "npx git-cliff -o CHANGELOG.md",
+        "git add -A"
       ]
     },
     "npm": {
       "publish": true
     }
-  },
-  "auto-changelog": {
-    "output": "CHANGELOG.md",
-    "tagPrefix": "service/",
-    "unreleased": true,
-    "commitLimit": false,
-    "hideCredit": true
   }
 }