@inharness-ai/claude4spec 1.0.0

package/dist/server/serialization/serializers/ui-view.js

@@ -0,0 +1,124 @@
+import { registerSerializer } from '../registry.js';
+function readParams(entity) {
+    const raw = entity.data.params;
+    if (!Array.isArray(raw))
+        return [];
+    return raw
+        .filter((p) => p !== null && typeof p === 'object')
+        .map((p) => ({
+        name: String(p.name ?? ''),
+        in: String(p.in ?? ''),
+        ...(typeof p.type === 'string' ? { type: p.type } : {}),
+        ...(typeof p.required === 'boolean' ? { required: p.required } : {}),
+        ...(typeof p.default === 'string' ? { default: p.default } : {}),
+        ...(typeof p.description === 'string' ? { description: p.description } : {}),
+    }));
+}
+function baseSingle(entity) {
+    return {
+        type: 'ui-view',
+        slug: entity.slug,
+        name: entity.data.name ?? entity.slug,
+        url: entity.data.url ?? null,
+        description: entity.data.description ?? null,
+        params: readParams(entity),
+        tags: entity.tags,
+    };
+}
+function trimItem(entity) {
+    const params = readParams(entity);
+    return {
+        type: 'ui-view',
+        slug: entity.slug,
+        name: entity.data.name ?? entity.slug,
+        url: entity.data.url ?? null,
+        description: entity.data.description ?? null,
+        paramCount: params.length,
+        tags: entity.tags,
+    };
+}
+const PARAM_OBJECT_SCHEMA = {
+    type: 'object',
+    required: ['name', 'in'],
+    properties: {
+        name: { type: 'string' },
+        in: { type: 'string', enum: ['path', 'query', 'hash'] },
+        type: { type: 'string' },
+        required: { type: 'boolean' },
+        default: { type: 'string' },
+        description: { type: 'string' },
+    },
+    additionalProperties: false,
+};
+const SINGLE_ELEMENT_SCHEMA = {
+    type: 'object',
+    required: ['type', 'slug', 'name', 'params', 'tags'],
+    properties: {
+        type: { const: 'ui-view' },
+        slug: { type: 'string' },
+        name: { type: 'string' },
+        url: { type: ['string', 'null'] },
+        description: { type: ['string', 'null'] },
+        params: { type: 'array', items: PARAM_OBJECT_SCHEMA },
+        tags: { type: 'array', items: { type: 'string' } },
+    },
+};
+const uiViewSerializer = {
+    type: 'ui-view',
+    version: '1.0.0',
+    inlineMention: (entity) => ({
+        type: 'ui-view',
+        slug: entity.slug,
+        label: entity.data.name ?? entity.slug,
+        url: entity.data.url ?? null,
+        href: `/ui-views/${entity.slug}`,
+    }),
+    singleElement: (entity) => baseSingle(entity),
+    elementListItem: (entity) => trimItem(entity),
+    taggedListItem: (entity) => trimItem(entity),
+    detail: (entity, ctx) => {
+        const base = baseSingle(entity);
+        const references = ctx.reader.findSectionReferences('ui-view', entity.id).map((r) => ({
+            anchor: r.anchor,
+            pagePath: r.pagePath,
+            headingText: r.headingText,
+            relation: r.relation,
+        }));
+        return {
+            ...base,
+            _references: references,
+        };
+    },
+    schema: (view) => {
+        if (view === 'single_element' || view === 'detail')
+            return SINGLE_ELEMENT_SCHEMA;
+        if (view === 'inline_mention') {
+            return {
+                type: 'object',
+                required: ['type', 'slug', 'label', 'href'],
+                properties: {
+                    type: { const: 'ui-view' },
+                    slug: { type: 'string' },
+                    label: { type: 'string' },
+                    url: { type: ['string', 'null'] },
+                    href: { type: 'string' },
+                },
+            };
+        }
+        return {
+            type: 'object',
+            required: ['type', 'slug', 'name', 'paramCount', 'tags'],
+            properties: {
+                type: { const: 'ui-view' },
+                slug: { type: 'string' },
+                name: { type: 'string' },
+                url: { type: ['string', 'null'] },
+                description: { type: ['string', 'null'] },
+                paramCount: { type: 'number' },
+                tags: { type: 'array', items: { type: 'string' } },
+            },
+        };
+    },
+};
+registerSerializer(uiViewSerializer);
+//# sourceMappingURL=ui-view.js.map

package/dist/server/serialization/serializers/ui-view.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui-view.js","sourceRoot":"","sources":["../../../../src/server/serialization/serializers/ui-view.ts"],"names":[],"mappings":"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"}

package/dist/server/serialization/snapshot.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Host-level snapshot/restore/diff helpers for M17.
+ *
+ * Plugin manifest slots are owner-of-shape (each EntitySerializer decides what
+ * `SnapshotData` looks like). These helpers route through the plugin host:
+ *   - `snapshotEntity(host, type, ...)` — calls `serializer.snapshot(...)`;
+ *     throws SnapshotNotImplementedError if the plugin has no snapshot slot
+ *     (snapshot is *required* for M17 participation, unlike read-only views
+ *     which fall back to raw JSON).
+ *   - `restoreEntity(host, type, ...)` — calls `serializer.restore(...)`.
+ *   - `diffEntity(host, type, a, b, slug)` — calls `serializer.diff(...)`
+ *     when present, otherwise computes a default deep-diff.
+ */
+import type { PluginHost } from '../core/plugin-host/types.js';
+import type { EntityDiff, RestoreContext, RestoreResult, SerializeContext, SnapshotData } from './types.js';
+export declare function snapshotEntity(host: PluginHost, type: string, entity: unknown, ctx: SerializeContext): SnapshotData;
+export declare function restoreEntity(host: PluginHost, type: string, data: SnapshotData, ctx: RestoreContext): RestoreResult;
+export declare function diffEntity(host: PluginHost, type: string, a: SnapshotData, b: SnapshotData, slug: string): EntityDiff;
+/** Compute deep-diff between two SnapshotData JSONs and wrap as EntityDiff. */
+export declare function defaultDeepDiff(type: string, slug: string, a: SnapshotData, b: SnapshotData): EntityDiff;
+/** Stable JSON canonicalization — sort object keys recursively. Arrays kept in order. */
+export declare function canonicalize(value: unknown): unknown;

package/dist/server/serialization/snapshot.js

@@ -0,0 +1,102 @@
+/**
+ * Host-level snapshot/restore/diff helpers for M17.
+ *
+ * Plugin manifest slots are owner-of-shape (each EntitySerializer decides what
+ * `SnapshotData` looks like). These helpers route through the plugin host:
+ *   - `snapshotEntity(host, type, ...)` — calls `serializer.snapshot(...)`;
+ *     throws SnapshotNotImplementedError if the plugin has no snapshot slot
+ *     (snapshot is *required* for M17 participation, unlike read-only views
+ *     which fall back to raw JSON).
+ *   - `restoreEntity(host, type, ...)` — calls `serializer.restore(...)`.
+ *   - `diffEntity(host, type, a, b, slug)` — calls `serializer.diff(...)`
+ *     when present, otherwise computes a default deep-diff.
+ */
+import { SnapshotNotImplementedError } from './types.js';
+export function snapshotEntity(host, type, entity, ctx) {
+    const module = host.getEntity(type);
+    if (!module)
+        throw new SnapshotNotImplementedError(type);
+    const fn = module.serializer.snapshot;
+    if (!fn)
+        throw new SnapshotNotImplementedError(type);
+    return fn(entity, ctx);
+}
+export function restoreEntity(host, type, data, ctx) {
+    const module = host.getEntity(type);
+    if (!module)
+        throw new SnapshotNotImplementedError(type);
+    const fn = module.serializer.restore;
+    if (!fn)
+        throw new SnapshotNotImplementedError(type);
+    return fn(data, ctx);
+}
+export function diffEntity(host, type, a, b, slug) {
+    const module = host.getEntity(type);
+    if (!module) {
+        // Inactive plugin — fall back to default; consumers (UI, M18) will see raw deep-diff.
+        return defaultDeepDiff(type, slug, a, b);
+    }
+    const fn = module.serializer.diff;
+    if (!fn)
+        return defaultDeepDiff(type, slug, a, b);
+    return fn(a, b, slug);
+}
+/** Compute deep-diff between two SnapshotData JSONs and wrap as EntityDiff. */
+export function defaultDeepDiff(type, slug, a, b) {
+    if (a == null && b == null)
+        return { type, slug, op: 'noop' };
+    if (a == null)
+        return { type, slug, op: 'created', raw: deepDiffPartition(undefined, b) };
+    if (b == null)
+        return { type, slug, op: 'deleted', raw: deepDiffPartition(a, undefined) };
+    if (deepEqual(a, b))
+        return { type, slug, op: 'noop' };
+    return { type, slug, op: 'modified', raw: deepDiffPartition(a, b) };
+}
+function deepDiffPartition(a, b) {
+    const added = {};
+    const removed = {};
+    const changed = {};
+    partition('', a, b, added, removed, changed);
+    return { added, removed, changed };
+}
+function partition(prefix, a, b, added, removed, changed) {
+    if (deepEqual(a, b))
+        return;
+    if (a === undefined) {
+        added[prefix || '/'] = b;
+        return;
+    }
+    if (b === undefined) {
+        removed[prefix || '/'] = a;
+        return;
+    }
+    if (!isObj(a) || !isObj(b)) {
+        changed[prefix || '/'] = { from: a, to: b };
+        return;
+    }
+    const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+    for (const key of keys) {
+        const sub = prefix ? `${prefix}.${key}` : key;
+        partition(sub, a[key], b[key], added, removed, changed);
+    }
+}
+function isObj(v) {
+    return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+function deepEqual(a, b) {
+    return JSON.stringify(canonicalize(a)) === JSON.stringify(canonicalize(b));
+}
+/** Stable JSON canonicalization — sort object keys recursively. Arrays kept in order. */
+export function canonicalize(value) {
+    if (value === null || typeof value !== 'object')
+        return value;
+    if (Array.isArray(value))
+        return value.map(canonicalize);
+    const sorted = {};
+    for (const key of Object.keys(value).sort()) {
+        sorted[key] = canonicalize(value[key]);
+    }
+    return sorted;
+}
+//# sourceMappingURL=snapshot.js.map

package/dist/server/serialization/snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.js","sourceRoot":"","sources":["../../../src/server/serialization/snapshot.ts"],"names":[],"mappings":"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"}

package/dist/server/serialization/types.d.ts

@@ -0,0 +1,70 @@
+import type { RawEntityReader } from '../domain/raw-entity-reader.js';
+import type { EntityWriter } from './writer.js';
+export type ViewKind = 'inline_mention' | 'single_element' | 'element_list_item' | 'tagged_list_item' | 'detail';
+export type JsonSchema = Record<string, unknown>;
+export interface SerializeContext {
+    reader: RawEntityReader;
+    depth: number;
+    maxDepth: number;
+}
+export type SerializeFn<T> = (entity: T, ctx: SerializeContext) => unknown;
+/** Plugin decides shape; recommendation: similar to single_element + tags + relations. */
+export type SnapshotData = unknown;
+export type FieldChange = Record<string, unknown>;
+export interface EntityDiff {
+    type: string;
+    slug: string;
+    op: 'created' | 'deleted' | 'modified' | 'noop';
+    /** Plugin-defined structured changes (e.g. dto_added, tag_removed, ...). */
+    changes?: Record<string, unknown>;
+    /** Default deep-diff fallback when plugin does not override `diff`. */
+    raw?: {
+        added: Record<string, unknown>;
+        removed: Record<string, unknown>;
+        changed: Record<string, unknown>;
+    };
+}
+export interface RestoreContext {
+    reader: RawEntityReader;
+    /** Normal write-API per type — restore goes through `entity_version` capture. */
+    writer: EntityWriter;
+    /** Informational: which release we're restoring from (does not change UPSERT semantics). */
+    releaseId: number | null;
+    /** Who initiated the restore — passed through to entity_version.changed_by. */
+    actor: 'user' | 'agent';
+}
+export interface RestoreResult<T = unknown> {
+    op: 'created' | 'updated' | 'deleted' | 'noop';
+    entity: T | null;
+    warnings?: string[];
+}
+export declare class SnapshotNotImplementedError extends Error {
+    constructor(type: string);
+}
+export interface EntitySerializer<T = unknown> {
+    type: string;
+    version: string;
+    inlineMention?: SerializeFn<T>;
+    singleElement?: SerializeFn<T>;
+    elementListItem?: SerializeFn<T>;
+    taggedListItem?: SerializeFn<T>;
+    detail?: SerializeFn<T>;
+    schema?: (view: ViewKind) => JsonSchema;
+    /** Deterministic, byte-identical snapshot. Pure function of state — no clock, no random. */
+    snapshot?: (entity: T, ctx: SerializeContext) => SnapshotData;
+    /**
+     * Inverse of snapshot — UPSERT through normal write-API; idempotent.
+     * Result entity is the domain type (Endpoint/Dto/...), not the read-view T,
+     * so restore is intentionally typed `RestoreResult<unknown>` — consumers
+     * downcast on per-type basis.
+     */
+    restore?: (data: SnapshotData, ctx: RestoreContext) => RestoreResult;
+    /** Optional semantic diff. Falls back to default deep-diff when omitted. */
+    diff?: (a: SnapshotData, b: SnapshotData, slug: string) => EntityDiff;
+}
+export interface SerializeResult {
+    data: unknown;
+    fallback: boolean;
+    error?: string;
+    brokenRefs?: string[];
+}

package/dist/server/serialization/types.js

@@ -0,0 +1,7 @@
+export class SnapshotNotImplementedError extends Error {
+    constructor(type) {
+        super(`type '${type}' has no snapshot slot — cannot participate in M17 release`);
+        this.name = 'SnapshotNotImplementedError';
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/server/serialization/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/server/serialization/types.ts"],"names":[],"mappings":"AAqDA,MAAM,OAAO,2BAA4B,SAAQ,KAAK;IACpD,YAAY,IAAY;QACtB,KAAK,CAAC,SAAS,IAAI,4DAA4D,CAAC,CAAC;QACjF,IAAI,CAAC,IAAI,GAAG,6BAA6B,CAAC;IAC5C,CAAC;CACF"}

package/dist/server/serialization/writer.d.ts

@@ -0,0 +1,41 @@
+/**
+ * EntityWriter — normal write-API surface used by `EntitySerializer.restore()`.
+ * Each plugin's restore slot calls type-specific methods which delegate to the
+ * per-type service. All mutations end up in `entity_version` with
+ * `release_id = NULL` (append-only — M17 decyzja 7).
+ *
+ * Phase 1: declared as type-only.
+ * Phase 2: per-plugin restore() consumes this surface.
+ * Phase 6: concrete implementation constructed by `releaseService` from the
+ * active per-type services + a tag/junction adapter.
+ */
+import type { Ac, AcCreateInput, ChangedBy, DatabaseTable, DatabaseTableCreateInput, Dto, DtoCreateInput, Endpoint, EndpointCreateInput, EndpointDtoRelation, UiView, UiViewCreateInput } from '../../shared/entities.js';
+import type { RawEntityType } from '../domain/raw-entity-reader.js';
+export interface UpsertResult<T> {
+    entity: T;
+    op: 'created' | 'updated';
+    warnings?: string[];
+}
+export interface EntityWriter {
+    upsertEndpoint(slug: string, input: EndpointCreateInput, actor: ChangedBy): UpsertResult<Endpoint>;
+    upsertDto(slug: string, input: DtoCreateInput, actor: ChangedBy): UpsertResult<Dto>;
+    upsertDatabaseTable(slug: string, input: DatabaseTableCreateInput, actor: ChangedBy): UpsertResult<DatabaseTable>;
+    upsertUiView(slug: string, input: UiViewCreateInput, actor: ChangedBy): UpsertResult<UiView>;
+    upsertAc(slug: string, input: AcCreateInput, actor: ChangedBy): UpsertResult<Ac>;
+    /** Sync endpoint↔dto junction to a target list. Idempotent: link missing, unlink extra. */
+    syncEndpointDtos(endpointSlug: string, target: Array<{
+        dtoSlug: string;
+        relation: EndpointDtoRelation;
+        statusCode: number | null;
+    }>): {
+        linked: number;
+        unlinked: number;
+        warnings: string[];
+    };
+    /** Sync entity tags to a target list. Idempotent. */
+    syncTags(type: RawEntityType, slug: string, tags: string[]): void;
+    /** Delete by slug — generates a `delete` row in entity_version. */
+    delete(type: RawEntityType, slug: string, actor: ChangedBy): {
+        deleted: boolean;
+    };
+}

package/dist/server/serialization/writer.js

@@ -0,0 +1,13 @@
+/**
+ * EntityWriter — normal write-API surface used by `EntitySerializer.restore()`.
+ * Each plugin's restore slot calls type-specific methods which delegate to the
+ * per-type service. All mutations end up in `entity_version` with
+ * `release_id = NULL` (append-only — M17 decyzja 7).
+ *
+ * Phase 1: declared as type-only.
+ * Phase 2: per-plugin restore() consumes this surface.
+ * Phase 6: concrete implementation constructed by `releaseService` from the
+ * active per-type services + a tag/junction adapter.
+ */
+export {};
+//# sourceMappingURL=writer.js.map

package/dist/server/serialization/writer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"writer.js","sourceRoot":"","sources":["../../../src/server/serialization/writer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}

package/dist/server/services/brief.d.ts

@@ -0,0 +1,86 @@
+/**
+ * M21 BriefService — thin wrapper over the second `PagesService` instance
+ * mounted on `briefsDir`. Briefs are markdown files with mandatory YAML
+ * frontmatter (`type: brief`, `from_release`, `to_release`, ...). The file
+ * itself is the source of truth (consumed both by humans in UI and by coding
+ * agents in terminal). DB participation is limited to:
+ *   - `chat_thread.brief_path` (M05) for editorial threads
+ *   - `page_version` (M17 Phase 4) — automatic via shared PageVersionService
+ *
+ * Design notes:
+ *   - **Zero new tables**. Listing comes from PagesFrontmatterIndexer.
+ *   - **Optimistic concurrency** by sha256 hash of full content (frontmatter+body).
+ *   - **Immutable frontmatter** keys protected: type/from_release/to_release/
+ *     generated_at/generator_version. Mutation attempt → DomainError.
+ */
+import type { Brief, BriefChangedBy, BriefListItem, BriefThreadSummary } from '../../shared/entities.js';
+import type { PagesService } from './pages.js';
+import type { PagesWatcher } from '../fs/watcher.js';
+import type { PageVersionService } from './page-version.js';
+import type { PageSerializer } from './page-serializer.js';
+import type { ChatService } from './chat.js';
+import type { ReleaseService } from './release.js';
+import type { PagesFrontmatterIndexer } from './pages-frontmatter-indexer.js';
+export interface BriefServiceDeps {
+    briefsPages: PagesService;
+    briefsWatcher: PagesWatcher;
+    briefsSerializer: PageSerializer;
+    pageVersions: PageVersionService;
+    chatService: ChatService;
+    releaseService: ReleaseService;
+    frontmatterIndexer: PagesFrontmatterIndexer;
+}
+export interface BriefCreateOpts {
+    /** `null` = initial brief — pomijamy walidacje `fromRelease` i frontmatter trzyma `from_release: null`. */
+    fromReleaseName: string | null;
+    toReleaseName: string;
+    /**
+     * Ulotny prompt sterujący stylem/językiem/audytorium briefa. NIE jest
+     * zapisywany ani do frontmatter, ani do SQLite — klient dokleja go do
+     * pierwszej user-message w initial-thread po redirect.
+     */
+    additionalPrompt?: string;
+    suffix?: string;
+}
+export interface BriefUpdateContentOpts {
+    path: string;
+    content: string;
+    expectedHash?: string;
+    changedBy: BriefChangedBy;
+    changeSummary?: string;
+}
+export interface BriefUpdateFrontmatterOpts {
+    path: string;
+    patch: {
+        implemented?: boolean;
+    };
+    changedBy: BriefChangedBy;
+}
+export interface BriefListOpts {
+    implemented?: boolean;
+}
+export declare class BriefService {
+    private deps;
+    constructor(deps: BriefServiceDeps);
+    getBrief(path: string): Promise<Brief>;
+    listBriefs(opts?: BriefListOpts): BriefListItem[];
+    listThreadsForBrief(path: string): BriefThreadSummary[];
+    createBrief(opts: BriefCreateOpts): Promise<{
+        briefPath: string;
+        initialThreadId: string;
+    }>;
+    updateContent(opts: BriefUpdateContentOpts): Promise<{
+        newHash: string;
+    }>;
+    updateFrontmatter(opts: BriefUpdateFrontmatterOpts): Promise<Brief>;
+    createThreadForBrief(briefPath: string, name?: string | null): {
+        threadId: string;
+    };
+    private absPath;
+    private allocatePath;
+}
+export declare class ConflictError extends Error {
+    readonly code: string;
+    readonly currentHash: string;
+    constructor(code: string, message: string, currentHash: string);
+}