@xandreed/core 0.3.0

package/dist/spec/codec.js

@@ -0,0 +1,123 @@
+import { Array as Arr, Data, Effect, Option, Schema } from "effect";
+import { SpecDoc } from "./SpecDoc.js";
+import { SpecSlug as SpecSlugSchema } from "./SpecDoc.js";
+import { parseFrontmatter } from "./frontmatter.js";
+
+export class SpecDocParseError extends Data.TaggedError("SpecDocParseError") {
+}
+const SECTION_HEADERS = ["Acceptance", "Checks", "Constraints", "Non-goals"], emptyBullets = {
+  Acceptance: [],
+  Checks: [],
+  Constraints: [],
+  "Non-goals": []
+}, parseSections = (body) => {
+  const folded = body.split(`
+`).reduce((acc, rawLine) => {
+    if (Option.isSome(acc.error))
+      return acc;
+    const line = rawLine.trimEnd();
+    if (line.startsWith("# "))
+      return line === "# Goal" ? { ...acc, current: "goal" } : { ...acc, error: Option.some(`unknown top-level section "${line}" (only "# Goal")`) };
+    if (line.startsWith("## ")) {
+      const header = line.slice(3).trim(), known = SECTION_HEADERS.find((h) => h === header);
+      return known === void 0 ? {
+        ...acc,
+        error: Option.some(`unknown section "## ${header}" (allowed: ${SECTION_HEADERS.join(", ")})`)
+      } : { ...acc, current: known };
+    }
+    if (acc.current === "goal")
+      return { ...acc, goalLines: [...acc.goalLines, line] };
+    if (acc.current !== "none" && line.trim().startsWith("- ")) {
+      const bullet = line.trim().slice(2).trim();
+      return bullet.length === 0 ? acc : {
+        ...acc,
+        bullets: {
+          ...acc.bullets,
+          [acc.current]: [...acc.bullets[acc.current], bullet]
+        }
+      };
+    }
+    if (acc.current !== "none" && line.trim().length > 0)
+      return {
+        ...acc,
+        error: Option.some(`section "## ${acc.current}" only takes "- " bullets (got: "${line.trim()}")`)
+      };
+    return acc;
+  }, { current: "none", goalLines: [], bullets: emptyBullets, error: Option.none() });
+  if (Option.isSome(folded.error))
+    return Effect.fail(new SpecDocParseError({ message: folded.error.value }));
+  const goal = folded.goalLines.join(`
+`).trim();
+  if (goal.length === 0)
+    return Effect.fail(new SpecDocParseError({ message: 'missing "# Goal" section' }));
+  return Effect.succeed({ goal, bullets: folded.bullets });
+}, parseCheckBullet = (bullet) => {
+  const colon = bullet.indexOf(":");
+  if (colon === -1)
+    return Effect.fail(new SpecDocParseError({ message: `check bullet needs "name: command" (got "${bullet}")` }));
+  return Effect.succeed({
+    name: bullet.slice(0, colon).trim(),
+    command: bullet.slice(colon + 1).trim()
+  });
+};
+export const decodeSpecDocText = (slug, text) => Effect.gen(function* () {
+  const fm = yield* Option.match(parseFrontmatter(text), {
+    onNone: () => Effect.fail(new SpecDocParseError({ message: "missing/unterminated frontmatter fence" })),
+    onSome: Effect.succeed
+  }), sections = yield* parseSections(fm.body), checks = yield* Effect.forEach(sections.bullets.Checks, parseCheckBullet), fields = fm.fields, numeric = (key, fallback) => {
+    const raw = fields[key];
+    return raw === void 0 || raw.length === 0 ? fallback : Number(raw);
+  }, candidate = {
+    slug,
+    status: fields.status ?? "draft",
+    created: fields.created ?? "",
+    ...fields.locked !== void 0 && fields.locked.length > 0 ? { locked: fields.locked } : {},
+    goal: sections.goal,
+    acceptance: sections.bullets.Acceptance,
+    constraints: sections.bullets.Constraints,
+    nonGoals: sections.bullets["Non-goals"],
+    checks,
+    limits: {
+      maxAttempts: numeric("maxAttempts", 3),
+      budgetMinutes: numeric("budgetMinutes", 15)
+    },
+    gates: {
+      ...fields.gatesConfig !== void 0 && fields.gatesConfig.length > 0 ? { config: fields.gatesConfig } : {},
+      ...fields.testCommand !== void 0 && fields.testCommand.length > 0 ? { testCommand: fields.testCommand } : {},
+      ...fields.noTest !== void 0 ? { noTest: fields.noTest === "true" } : {},
+      ...fields.judge !== void 0 ? { judge: fields.judge === "true" } : {}
+    }
+  };
+  return yield* Schema.decodeUnknown(SpecDoc)(candidate).pipe(Effect.mapError((error) => new SpecDocParseError({ message: String(error) })));
+}), normalizeBullet = (text) => text.replace(/\s+/g, " ").trim(), encodeSpecDocText = (doc) => {
+  const frontmatter = [
+    "---",
+    "version: 1",
+    `status: ${doc.status}`,
+    `created: ${doc.created}`,
+    ...Option.match(doc.locked, { onNone: () => [], onSome: (at) => [`locked: ${at}`] }),
+    `maxAttempts: ${doc.limits.maxAttempts}`,
+    `budgetMinutes: ${doc.limits.budgetMinutes}`,
+    ...Option.match(doc.gates.config, { onNone: () => [], onSome: (c) => [`gatesConfig: ${c}`] }),
+    ...Option.match(doc.gates.testCommand, {
+      onNone: () => [],
+      onSome: (c) => [`testCommand: ${c}`]
+    }),
+    ...doc.gates.noTest ? ["noTest: true"] : [],
+    ...doc.gates.judge ? [] : ["judge: false"],
+    "---"
+  ].join(`
+`), section = (header, items) => items.length === 0 ? "" : `
+
+## ${header}
+${items.map((item) => `- ${item}`).join(`
+`)}`;
+  return `${frontmatter}
+
+# Goal
+${doc.goal}${section("Acceptance", doc.acceptance.map(normalizeBullet))}${section("Checks", doc.checks.map((check) => `${check.name}: ${check.command}`))}${section("Constraints", doc.constraints.map(normalizeBullet))}${section("Non-goals", doc.nonGoals.map(normalizeBullet))}
+`;
+}, specSlug = (goal) => {
+  const kebab = goal.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40).replace(/-+$/, "");
+  return SpecSlugSchema.make(kebab.length === 0 ? "spec" : kebab);
+}, uniqueSlug = (base, taken) => taken(base) ? SpecSlugSchema.make(Option.getOrElse(Arr.findFirst(Arr.range(2, 99), (n) => !taken(`${base}-${n}`)).pipe(Option.map((n) => `${base}-${n}`)), () => `${base}-${Date.now()}`)) : base;

package/dist/spec/codec.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/spec/frontmatter.d.ts

@@ -0,0 +1,16 @@
+import { Option } from "effect";
+export interface Frontmatter {
+    /** Flat `key: value` pairs from the fence. No arrays / nested YAML. */
+    readonly fields: Record<string, string>;
+    /** Everything after the closing fence, leading blank lines trimmed. */
+    readonly body: string;
+}
+/**
+ * The one frontmatter parser shared by scopes, skills, and agent definitions:
+ * a `---\n…\n---` fence at the top with `key: value` lines inside, then a
+ * free-form body. Values are taken verbatim, trimmed, surrounding quotes
+ * stripped; comment (`#`) and blank lines are skipped. No arrays, no nested
+ * YAML, no multi-line values. Returns `None` when the fence is missing or
+ * unterminated. Callers decide which `fields` are required.
+ */
+export declare const parseFrontmatter: (content: string) => Option.Option<Frontmatter>;

package/dist/spec/frontmatter.js

@@ -0,0 +1,25 @@
+import { Option } from "effect";
+export const parseFrontmatter = (content) => {
+  if (!content.startsWith("---"))
+    return Option.none();
+  const rest = content.slice(3), lfIndex = rest.indexOf(`
+`);
+  if (lfIndex === -1)
+    return Option.none();
+  const afterFirstFence = rest.slice(lfIndex + 1), closeIndex = afterFirstFence.indexOf(`
+---`);
+  if (closeIndex === -1)
+    return Option.none();
+  const frontmatter = afterFirstFence.slice(0, closeIndex), body = afterFirstFence.slice(closeIndex + 4).replace(/^\n+/, ""), fields = Object.fromEntries(frontmatter.split(`
+`).flatMap((line) => {
+    const trimmed = line.trim();
+    if (trimmed === "" || trimmed.startsWith("#"))
+      return [];
+    const colon = trimmed.indexOf(":");
+    if (colon === -1)
+      return [];
+    const key = trimmed.slice(0, colon).trim(), value = trimmed.slice(colon + 1).trim().replace(/^["']|["']$/g, "");
+    return [[key, value]];
+  }));
+  return Option.some({ fields, body });
+};

package/dist/util/json.d.ts

@@ -0,0 +1,19 @@
+import { Effect, Either, Option } from "effect";
+/**
+ * Parse JSON with CORRUPT ≠ ABSENT semantics: malformed text logs a warning
+ * naming the source and yields `None`. Config readers fall back to their
+ * empty shape either way — but a corrupt `auth.json` silently reading as
+ * "logged out", or a corrupt `config.json` as "defaults", gives the user
+ * zero signal about the actual problem (audit class L8).
+ */
+export declare const parseJsonWarn: (text: string, where: string) => Effect.Effect<Option.Option<unknown>>;
+/** The record-or-empty projection every config reader wants after parse. */
+export declare const asJsonRecord: (value: Option.Option<unknown>) => Record<string, unknown>;
+/** SILENT parse-to-Option — for wire noise (a garbage WS frame) where
+ *  dropping without a log is the design; configs use {@link parseJsonWarn}. */
+export declare const parseJsonOption: (text: string) => Option.Option<unknown>;
+/** Decode append-only JSONL text: one JSON value per line, each decoded by
+ *  `decode`; a corrupt or undecodable LINE is skipped (append-only files
+ *  corrupt at a line boundary — one bad row must not brick the history).
+ *  The shared machinery of the smith memory ledger and the social ledger. */
+export declare const decodeJsonLines: <A, E>(text: string, decode: (value: unknown) => Either.Either<A, E>) => ReadonlyArray<A>;

package/dist/util/json.js

@@ -0,0 +1,15 @@
+import { Effect, Either, Option } from "effect";
+export const parseJsonWarn = (text, where) => Either.match(Either.try(() => JSON.parse(text)), {
+  onLeft: (error) => Effect.logWarning(`${where}: unreadable JSON \u2014 treating as empty: ${String(error)}`).pipe(Effect.as(Option.none())),
+  onRight: (value) => Effect.succeed(Option.some(value))
+}), asJsonRecord = (value) => Option.match(value, {
+  onNone: () => ({}),
+  onSome: (parsed) => typeof parsed === "object" && parsed !== null ? parsed : {}
+}), parseJsonOption = (text) => Either.getRight(Either.try(() => JSON.parse(text))), decodeJsonLines = (text, decode) => text.split(`
+`).filter((line) => line.trim().length > 0).flatMap((line) => Either.try(() => JSON.parse(line)).pipe(Either.match({
+  onLeft: () => [],
+  onRight: (parsed) => Either.match(decode(parsed), {
+    onLeft: () => [],
+    onRight: (decoded) => [decoded]
+  })
+})));

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@xandreed/core",
+  "version": "0.3.0",
+  "private": false,
+  "type": "module",
+  "description": "The agent kernel of the new line: entities, ports, the provider-agnostic agent loop, and the session chassis — pure Effect, no IO, no provider SDKs.",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@effect/ai": "0.35.0",
+    "effect": "3.21.4"
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "skills",
+    "profiles",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "license": "MIT"
+}