Initial core package commit

.agents/skills/grill-me/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: grill-me
+description: A relentless interview to sharpen a plan or design.
+disable-model-invocation: true
+---
+
+Call the Skill tool with "grilling".

.agents/skills/grill-me/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Grill Me"
+  short_description: "Sharpen a plan through interview"
+policy:
+  allow_implicit_invocation: false

.gitignore

@@ -439,3 +439,5 @@ devenv.local.nix
 
 # pre-commit
 .pre-commit-config.yaml
+
+vitest.config.*.timestamp*

nx.json

@@ -16,12 +16,34 @@
         "typecheck": true,
         "build": false,
         "verboseOutput": false
-      }
+      },
+      "exclude": ["packages/core/*"]
     },
     "@storm-software/workspace-tools/plugins/typescript",
     "@storm-software/workspace-tools/plugins/typescript/untyped",
     "@storm-software/workspace-tools/plugins/typescript/tsdown",
-    "@powerlines/nx/plugin"
+    "@powerlines/nx/plugin",
+    {
+      "plugin": "@nx/js/typescript",
+      "include": ["packages/core/*"],
+      "options": {
+        "typecheck": {
+          "targetName": "typecheck"
+        },
+        "build": {
+          "targetName": "build",
+          "configName": "tsconfig.lib.json"
+        }
+      }
+    },
+    {
+      "plugin": "@nx/vitest",
+      "options": {
+        "testTargetName": "test",
+        "ciTargetName": "test-ci",
+        "testMode": "watch"
+      }
+    }
   ],
   "sync": {
     "applyChanges": true,

package.json

@@ -86,6 +86,7 @@
     "@storm-software/pnpm-tools": "catalog:",
     "@storm-software/prettier": "catalog:",
     "@storm-software/tsconfig": "catalog:",
+    "@storm-software/tsdoc": "catalog:",
     "@storm-software/untyped": "catalog:",
     "@storm-software/workspace-tools": "catalog:",
     "@types/node": "catalog:",
@@ -94,6 +95,7 @@
     "eslint": "catalog:",
     "lefthook": "catalog:",
     "log4brains": "catalog:",
+    "markdownlint-cli2": "catalog:",
     "nx": "catalog:",
     "prettier": "catalog:",
     "rimraf": "catalog:",

packages/core/README.md

@@ -0,0 +1,38 @@
+# `@sourcebook/core`
+
+Core orchestration primitives for agent-driven source documentation.
+
+```ts
+import {
+  createDocumentJob,
+  createFakeAgentStage,
+  createMarkdownRendererStage,
+  createPipeline,
+  executePipeline,
+  MemoryCheckpointStore
+} from "@sourcebook/core"
+
+const pipeline = createPipeline({
+  id: "project-docs",
+  version: "1",
+  stages: [
+    createFakeAgentStage({ documents }),
+    createMarkdownRendererStage({ outputDirectory: "docs" })
+  ]
+})
+
+const execution = executePipeline(pipeline, createDocumentJob(job), {
+  checkpointStore: new MemoryCheckpointStore()
+})
+
+for await (const event of execution.events) {
+  console.log(event.type)
+}
+
+const result = await execution.result
+```
+
+Stages run in declaration order and receive an `AbortSignal`. Checkpoints are
+reused only when the pipeline signature, stage version and configuration, and
+normalized stage input all match. Automatic retries require an idempotent
+stage unless explicitly overridden.

packages/core/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@sourcebook/core",
+  "version": "0.0.1",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!**/*.tsbuildinfo"
+  ],
+  "dependencies": {
+    "tslib": "catalog:",
+    "zod": "catalog:"
+  }
+}

packages/core/project.json

@@ -0,0 +1,9 @@
+{
+  "name": "core",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "packages/core/src",
+  "projectType": "library",
+  "tags": [],
+  "// targets": "to see all targets run: nx show project core --web",
+  "targets": {}
+}

packages/core/src/index.ts

@@ -0,0 +1,23 @@
+/* -------------------------------------------------------------------
+
+                   🗲 Storm Software - Sourcebook
+
+ This code was released as part of the Sourcebook project. Sourcebook
+ is maintained by Storm Software under the Apache-2.0 license, and is
+ free for commercial and private use. For more information, please visit
+ our licensing page at https://stormsoftware.com/licenses/projects/sourcebook.
+
+ Website:                  https://stormsoftware.com
+ Repository:               https://github.com/storm-software/sourcebook
+ Documentation:            https://docs.stormsoftware.com/projects/sourcebook
+ Contact:                  https://stormsoftware.com/contact
+
+ SPDX-License-Identifier:  Apache-2.0
+
+ ------------------------------------------------------------------- */
+
+export * from "./lib/checkpoint.js";
+export * from "./lib/fake-agent.js";
+export * from "./lib/markdown.js";
+export * from "./lib/model.js";
+export * from "./lib/pipeline.js";

packages/core/src/lib/checkpoint.ts

@@ -0,0 +1,68 @@
+/* -------------------------------------------------------------------
+
+                   🗲 Storm Software - Sourcebook
+
+ This code was released as part of the Sourcebook project. Sourcebook
+ is maintained by Storm Software under the Apache-2.0 license, and is
+ free for commercial and private use. For more information, please visit
+ our licensing page at https://stormsoftware.com/licenses/projects/sourcebook.
+
+ Website:                  https://stormsoftware.com
+ Repository:               https://github.com/storm-software/sourcebook
+ Documentation:            https://docs.stormsoftware.com/projects/sourcebook
+ Contact:                  https://stormsoftware.com/contact
+
+ SPDX-License-Identifier:  Apache-2.0
+
+ ------------------------------------------------------------------- */
+
+import type { DocumentJob } from "./model.js";
+import { DocumentJobSchema } from "./model.js";
+
+export interface PipelineCheckpoint {
+  key: string;
+  inputHash: string;
+  job: DocumentJob;
+  completedAt: string;
+}
+
+export interface CheckpointStore {
+  load: (
+    key: string,
+    signal?: AbortSignal
+  ) => Promise<PipelineCheckpoint | null>;
+  save: (checkpoint: PipelineCheckpoint, signal?: AbortSignal) => Promise<void>;
+}
+
+function cloneCheckpoint(checkpoint: PipelineCheckpoint): PipelineCheckpoint {
+  return {
+    ...checkpoint,
+    job: DocumentJobSchema.parse(structuredClone(checkpoint.job))
+  };
+}
+
+export class MemoryCheckpointStore implements CheckpointStore {
+  readonly #checkpoints = new Map<string, PipelineCheckpoint>();
+
+  async load(
+    key: string,
+    signal?: AbortSignal
+  ): Promise<PipelineCheckpoint | null> {
+    signal?.throwIfAborted();
+    const checkpoint = this.#checkpoints.get(key);
+
+    return checkpoint ? cloneCheckpoint(checkpoint) : null;
+  }
+
+  async save(
+    checkpoint: PipelineCheckpoint,
+    signal?: AbortSignal
+  ): Promise<void> {
+    signal?.throwIfAborted();
+    this.#checkpoints.set(checkpoint.key, cloneCheckpoint(checkpoint));
+  }
+
+  clear() {
+    this.#checkpoints.clear();
+  }
+}

packages/core/src/lib/fake-agent.ts

@@ -0,0 +1,48 @@
+/* -------------------------------------------------------------------
+
+                   🗲 Storm Software - Sourcebook
+
+ This code was released as part of the Sourcebook project. Sourcebook
+ is maintained by Storm Software under the Apache-2.0 license, and is
+ free for commercial and private use. For more information, please visit
+ our licensing page at https://stormsoftware.com/licenses/projects/sourcebook.
+
+ Website:                  https://stormsoftware.com
+ Repository:               https://github.com/storm-software/sourcebook
+ Documentation:            https://docs.stormsoftware.com/projects/sourcebook
+ Contact:                  https://stormsoftware.com/contact
+
+ SPDX-License-Identifier:  Apache-2.0
+
+ ------------------------------------------------------------------- */
+
+import type { DocumentPage } from "./model.js";
+import { DocumentPageSchema } from "./model.js";
+import type { PipelineStage } from "./pipeline.js";
+import { toJsonValue } from "./pipeline.js";
+
+export interface FakeAgentStageOptions {
+  id?: string;
+  version?: string;
+  documents: readonly DocumentPage[];
+}
+
+export function createFakeAgentStage(
+  options: FakeAgentStageOptions
+): PipelineStage {
+  const documents = options.documents.map(document =>
+    DocumentPageSchema.parse(document)
+  );
+
+  return {
+    id: options.id ?? "fake-agent",
+    kind: "agent",
+    version: options.version ?? "1",
+    idempotent: true,
+    config: toJsonValue({ documents }),
+    execute: ({ signal }) => {
+      signal.throwIfAborted();
+      return { documents: structuredClone(documents) };
+    }
+  };
+}