@akagilnc/pi-workflow-roles 0.1.1751

package/src/canonical-json.ts

@@ -0,0 +1,74 @@
+export const CANONICAL_JSON_VALIDATION_ERROR_CODE = "canonical-json-invalid" as const;
+
+export class CanonicalJsonValidationError extends Error {
+  readonly code = CANONICAL_JSON_VALIDATION_ERROR_CODE;
+
+  constructor(readonly path: string, readonly reason: string) {
+    super(`Canonical JSON validation failed at ${path}: ${reason}`);
+    this.name = "CanonicalJsonValidationError";
+  }
+}
+
+function childPath(path: string, segment: string | number): string {
+  return `${path}/${String(segment).replaceAll("~", "~0").replaceAll("/", "~1")}`;
+}
+
+function ownStringKeys(value: object, path: string): string[] {
+  const keys = Reflect.ownKeys(value);
+  if (keys.some((key) => typeof key === "symbol")) {
+    throw new CanonicalJsonValidationError(childPath(path, "<symbol>"), "symbol-keyed member is not a JSON member");
+  }
+  return keys as string[];
+}
+
+/** Deterministic serialization of the closed JSON value domain. */
+export function canonicalJson(value: unknown): string {
+  const ancestors = new WeakSet<object>();
+
+  const serialize = (item: unknown, path: string): string => {
+    if (item === null) return "null";
+    switch (typeof item) {
+      case "boolean":
+      case "string":
+        return JSON.stringify(item);
+      case "number":
+        if (!Number.isFinite(item)) throw new CanonicalJsonValidationError(path, "number must be finite");
+        return JSON.stringify(item);
+      case "undefined":
+      case "function":
+      case "symbol":
+      case "bigint":
+        throw new CanonicalJsonValidationError(path, `${typeof item} is not a JSON value`);
+      case "object": {
+        if (ancestors.has(item)) throw new CanonicalJsonValidationError(path, "cycle is not a JSON value");
+        ancestors.add(item);
+        try {
+          if (Array.isArray(item)) {
+            if (Object.getPrototypeOf(item) !== Array.prototype) throw new CanonicalJsonValidationError(path, "array must not be a custom object");
+            const keys = ownStringKeys(item, path);
+            const extraKey = keys.find((key) => key !== "length" && (!/^(0|[1-9][0-9]*)$/.test(key) || Number(key) >= item.length));
+            if (extraKey !== undefined) throw new CanonicalJsonValidationError(childPath(path, extraKey), "non-index array member is not a JSON member");
+            const values: string[] = [];
+            for (let index = 0; index < item.length; index += 1) {
+              if (!Object.hasOwn(item, index)) throw new CanonicalJsonValidationError(childPath(path, index), "sparse array slot is not a JSON value");
+              values.push(serialize(item[index], childPath(path, index)));
+            }
+            return `[${values.join(",")}]`;
+          }
+          const prototype = Object.getPrototypeOf(item);
+          if (prototype !== Object.prototype && prototype !== null) throw new CanonicalJsonValidationError(path, "object must be a plain record");
+          return `{${ownStringKeys(item, path).sort().map((key) => `${JSON.stringify(key)}:${serialize((item as Record<string, unknown>)[key], childPath(path, key))}`).join(",")}}`;
+        } finally {
+          ancestors.delete(item);
+        }
+      }
+    }
+    throw new Error("Unreachable canonical JSON value type");
+  };
+
+  return serialize(value, "$");
+}
+
+export function canonicalJsonBytes(value: unknown): Uint8Array {
+  return new TextEncoder().encode(canonicalJson(value));
+}

package/src/canonical-skill-binding.ts

@@ -0,0 +1,107 @@
+import { readFile, realpath } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, resolve } from "node:path";
+
+import { parseSkillBlock, stripFrontmatter } from "@earendil-works/pi-coding-agent";
+export type CanonicalSkillName = "tdd" | "code-review";
+
+export type CanonicalSkillSnapshot = Readonly<{
+  raw: string;
+  path: string;
+  baseDir: string;
+  body: string;
+  /** Plain skill text — no length/digest identity shell (ADR 0031). */
+  snapshotIdentity: Readonly<{ text: string }>;
+}>;
+
+export type CanonicalSkillEvidence<Name extends CanonicalSkillName = CanonicalSkillName> = Readonly<{
+  name: Name;
+  location: string;
+  content: string;
+  userMessage: string;
+}>;
+
+export type CanonicalSkillBinding<Name extends CanonicalSkillName = CanonicalSkillName> = Readonly<{
+  name: Name;
+  snapshot: CanonicalSkillSnapshot;
+  invocation(originalRequest: string): string;
+  captureExpansion(
+    prompt: string,
+    originalRequest: string,
+  ): CanonicalSkillEvidence<Name> | undefined;
+}>;
+
+export type AnyCanonicalSkillBinding =
+  | CanonicalSkillBinding<"tdd">
+  | CanonicalSkillBinding<"code-review">;
+
+export class CanonicalSkillUnavailableError extends Error {
+  readonly code = "canonical-skill-unavailable" as const;
+  constructor(readonly skillName: CanonicalSkillName, path: string, cause: unknown) {
+    super(`Canonical ${skillName} Skill is unavailable at ${path}`, { cause });
+    this.name = "CanonicalSkillUnavailableError";
+  }
+}
+
+export async function loadCanonicalSkillBinding(
+  name: CanonicalSkillName,
+): Promise<AnyCanonicalSkillBinding> {
+  const configuredPath = resolve(
+    homedir(),
+    `.agents/skills/${name}/SKILL.md`,
+  );
+  let path: string;
+  let raw: string;
+  try {
+    path = await realpath(configuredPath);
+    raw = await readFile(path, "utf8");
+  } catch (error) {
+    throw new CanonicalSkillUnavailableError(name, configuredPath, error);
+  }
+  const body = stripFrontmatter(raw).trim();
+  if (body.length === 0) {
+    throw new Error(`Canonical ${name} Skill is empty at ${path}`);
+  }
+  const snapshot: CanonicalSkillSnapshot = Object.freeze({
+    raw,
+    path,
+    baseDir: dirname(path),
+    body,
+    snapshotIdentity: Object.freeze({ text: raw }),
+  });
+  const binding: CanonicalSkillBinding<typeof name> = {
+    name,
+    snapshot,
+    invocation(originalRequest) {
+      return `/skill:${name} ${originalRequest}`;
+    },
+    captureExpansion(prompt, originalRequest) {
+      const parsed = parseSkillBlock(prompt);
+      const matchedPath =
+        parsed?.location === configuredPath
+          ? configuredPath
+          : parsed?.location === snapshot.path
+            ? snapshot.path
+            : undefined;
+      const expectedContent = matchedPath === undefined
+        ? undefined
+        : `References are relative to ${dirname(matchedPath)}.\n\n${snapshot.body}`;
+      const userMessage = parsed?.userMessage ?? "";
+      if (
+        parsed?.name !== name ||
+        matchedPath === undefined ||
+        parsed.content !== expectedContent ||
+        userMessage !== originalRequest
+      ) {
+        return undefined;
+      }
+      return Object.freeze({
+        name,
+        location: parsed.location,
+        content: parsed.content,
+        userMessage,
+      });
+    },
+  };
+  return Object.freeze(binding) as AnyCanonicalSkillBinding;
+}

package/src/collector-config.ts

@@ -0,0 +1,89 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+
+export const COLLECTOR_HOST = "github.com" as const;
+export const COLLECTOR_OWNER_PATTERN = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,37}[A-Za-z0-9])?$/;
+export const COLLECTOR_REPO_PATTERN = /^[A-Za-z0-9](?:[A-Za-z0-9._-]{0,98}[A-Za-z0-9])?$/;
+export const COLLECTOR_FIXED_KICKOFF =
+  "Start collection for the validated runtime-owned target. Observe GitHub materials and submit exactly one ak_collector_output when observation is complete.";
+
+export type CollectorRepository = {
+  display: string;
+  canonical: string;
+  owner: string;
+  repo: string;
+};
+
+export type CollectorRequestConfig = { id: string; requestBody: string };
+export type CollectorManifest = {
+  requests: readonly CollectorRequestConfig[];
+  canonicalJson: string;
+  digest: string;
+  sourcePath?: string;
+};
+
+function fail(message: string, cause?: unknown): never {
+  throw new Error(message, cause === undefined ? undefined : { cause });
+}
+
+function conservativeAscii(input: string): boolean {
+  for (let i = 0; i < input.length; i += 1) {
+    const code = input.charCodeAt(i);
+    if (code <= 0x1f || code === 0x7f || code > 0x7f) return false;
+  }
+  return true;
+}
+
+export function parseCollectorRepository(raw: unknown): CollectorRepository {
+  if (typeof raw !== "string" || raw.trim() !== raw || raw.length === 0) fail("Collector repository must be a string owner/repo");
+  if (!conservativeAscii(raw) || raw.includes("://") || /[?#@%\\ ]/.test(raw)) fail("Collector repository rejects URL syntax and non-identity bytes");
+  const parts = raw.split("/");
+  if (parts.length !== 2) fail("Collector repository must contain exactly one '/' separating owner and repo");
+  const [ownerDisplay, repoDisplay] = parts as [string, string];
+  if (!COLLECTOR_OWNER_PATTERN.test(ownerDisplay) || !COLLECTOR_REPO_PATTERN.test(repoDisplay)) fail("Collector repository does not match the conservative owner/repo grammar");
+  const owner = ownerDisplay.toLowerCase();
+  const repo = repoDisplay.toLowerCase();
+  return { display: raw, canonical: `${owner}/${repo}`, owner, repo };
+}
+
+export function parseCollectorPrNumber(raw: unknown): number {
+  if (typeof raw === "string" && !/^[1-9][0-9]*$/.test(raw)) fail("Collector pull request number must be a positive safe integer string");
+  if (typeof raw !== "string" && typeof raw !== "number") fail("Collector pull request number is required");
+  const value = Number(raw);
+  if (!Number.isSafeInteger(value) || value < 1) fail("Collector pull request number must be a positive safe integer");
+  return value;
+}
+
+function record(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function canonicalManifest(requests: readonly CollectorRequestConfig[]): string {
+  return `${JSON.stringify({ requests: requests.map((request) => ({ id: request.id, body: request.requestBody })) })}\n`;
+}
+
+export function emptyCollectorManifest(): CollectorManifest {
+  const canonicalJson = canonicalManifest([]);
+  return { requests: [], canonicalJson, digest: createHash("sha256").update(canonicalJson).digest("hex") };
+}
+
+/** Optional request configuration. It names requests, never expected observers. */
+export async function loadCollectorManifest(path: string): Promise<CollectorManifest> {
+  let bytes: Buffer;
+  try { bytes = await readFile(path); } catch (error) { fail(`Collector request manifest is unreadable at ${path}`, error); }
+  let parsed: unknown;
+  try { parsed = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes)); } catch (error) { fail("Collector request manifest must be UTF-8 JSON", error); }
+  if (!record(parsed)) fail("Collector request manifest must be an object");
+  const rawRequests = parsed.requests ?? [];
+  if (!Array.isArray(rawRequests)) fail("Collector request manifest requests must be an array");
+  const requests: CollectorRequestConfig[] = [];
+  const ids = new Set<string>();
+  for (const [index, item] of rawRequests.entries()) {
+    if (!record(item) || typeof item.id !== "string" || item.id.length === 0 || typeof item.body !== "string" || item.body.trim() === "") fail(`Collector request manifest requests[${index}] is invalid`);
+    if (ids.has(item.id)) fail(`Collector request manifest has duplicate request id "${item.id}"`);
+    ids.add(item.id);
+    requests.push({ id: item.id, requestBody: item.body });
+  }
+  const canonicalJson = canonicalManifest(requests);
+  return { requests, canonicalJson, digest: createHash("sha256").update(canonicalJson).digest("hex"), sourcePath: path };
+}