@spexcode/spec-core 0.6.2 → 0.6.3

package/dist/identity-presets.js

@@ -0,0 +1,132 @@
+// One browser-safe identity registry shared by backend validation and every dashboard projection.
+// Geometry is data so the React renderer and favicon serializer cannot drift into separate drawings.
+//
+// @@@ shape keys travel through two renderers - a shape's own attributes override the group's
+// fill/stroke, which is how a multi-colour mark fits a single-fg registry. Both consumers pass the keys
+// through verbatim: the string serializer spreads them as attributes, React spreads them as JSX props.
+// So a key must be valid in BOTH, which rules out hyphenated names (React wants strokeWidth) - hence a
+// painted seam outline rather than a stroked line, since per-shape stroke-width cannot be expressed.
+export const DEFAULT_PROJECT_ICON = 'spexcode';
+export const DEFAULT_GATEWAY_ICON = 'gateway';
+export const IDENTITY_PRESETS = Object.freeze([
+    {
+        // The brand mark: two brackets holding one file, cleft corner to corner and regenerated on the
+        // upper-right of the cleft. Painted rather than stroked — see the paint note below. Geometry is
+        // docs/brand/mark-dark.svg scaled by 24/512; the two surface gradients flatten to their midpoints
+        // because a 24-unit chip has no room for a ramp and the format carries no defs.
+        id: 'spexcode', label: 'SpexCode', bg: '#12161C', fg: '#EFE8D8',
+        shapes: [
+            { tag: 'path', d: 'M 4.500,4.500 L 9.750,4.500 L 9.750,6.656 L 6.656,6.656 L 6.656,17.344 L 9.750,17.344 L 9.750,19.500 L 4.500,19.500 Z', fill: '#EFE8D8', stroke: 'none' },
+            { tag: 'path', d: 'M 19.500,4.500 L 14.250,4.500 L 14.250,6.656 L 17.344,6.656 L 17.344,17.344 L 14.250,17.344 L 14.250,19.500 L 19.500,19.500 Z', fill: '#EFE8D8', stroke: 'none' },
+            { tag: 'path', d: 'M 15.281,15.281 L 11.731,13.057 L 12.269,10.943 L 8.719,8.719 L 8.719,15.281 Z', fill: '#327D95', stroke: 'none' },
+            { tag: 'path', d: 'M 8.719,8.719 L 12.269,10.943 L 11.731,13.057 L 15.281,15.281 L 15.281,12.000 L 12.000,8.719 Z', fill: '#82C3D6', stroke: 'none' },
+            { tag: 'path', d: 'M 8.569,8.957 L 11.946,11.073 L 11.408,13.186 L 15.132,15.520 L 15.431,15.043 L 12.054,12.927 L 12.592,10.814 L 8.868,8.480 Z', fill: '#E4F7FD', stroke: 'none' },
+        ],
+    },
+    {
+        id: 'gateway', label: 'Gateway', bg: '#155e75', fg: '#ecfeff',
+        shapes: [
+            { tag: 'path', d: 'm12 3 8 4.2-8 4.2-8-4.2Z' },
+            { tag: 'path', d: 'm4 11.2 8 4.2 8-4.2' },
+            { tag: 'path', d: 'm4 15.2 8 4.2 8-4.2' },
+        ],
+    },
+    {
+        id: 'mdi:rocket-launch', label: 'Rocket', bg: '#9f1239', fg: '#fff1f2',
+        shapes: [
+            { tag: 'path', d: 'M14.5 5.2c2.2-2.2 4.8-2 5.3-1.8.2.5.4 3.1-1.8 5.3l-5.5 5.5-4.2-4.2Z' },
+            { tag: 'path', d: 'm11.2 6.8-4.1.6-2.5 2.5 4.1.7' },
+            { tag: 'path', d: 'm16.4 12-1 4.7-2.5 2.5-.7-4.1' },
+            { tag: 'circle', cx: 16.1, cy: 7.1, r: 1.2 },
+            { tag: 'path', d: 'M7.6 14.6c-2.2.4-3.4 1.6-3.6 3.8 2.2-.2 3.4-1.4 3.8-3.6' },
+        ],
+    },
+    {
+        id: 'compass', label: 'Compass', bg: '#1d4ed8', fg: '#eff6ff',
+        shapes: [
+            { tag: 'circle', cx: 12, cy: 12, r: 8.5 },
+            { tag: 'path', d: 'm15.2 8.8-1.8 4.6-4.6 1.8 1.8-4.6Z' },
+        ],
+    },
+    {
+        id: 'terminal', label: 'Terminal', bg: '#3f3f46', fg: '#fafafa',
+        shapes: [
+            { tag: 'rect', x: 3.5, y: 4.5, width: 17, height: 15, rx: 2 },
+            { tag: 'path', d: 'm7 9 3 3-3 3' },
+            { tag: 'path', d: 'M12.5 15H17' },
+        ],
+    },
+    {
+        id: 'package', label: 'Package', bg: '#6d28d9', fg: '#f5f3ff',
+        shapes: [
+            { tag: 'path', d: 'm12 3 8 4.5v9L12 21l-8-4.5v-9Z' },
+            { tag: 'path', d: 'm4.3 7.7 7.7 4.4 7.7-4.4' },
+            { tag: 'path', d: 'M12 12.1V21' },
+        ],
+    },
+    {
+        id: 'database', label: 'Database', bg: '#a16207', fg: '#fefce8',
+        shapes: [
+            { tag: 'ellipse', cx: 12, cy: 6, rx: 7.5, ry: 3 },
+            { tag: 'path', d: 'M4.5 6v6c0 1.7 3.4 3 7.5 3s7.5-1.3 7.5-3V6' },
+            { tag: 'path', d: 'M4.5 12v6c0 1.7 3.4 3 7.5 3s7.5-1.3 7.5-3v-6' },
+        ],
+    },
+    {
+        id: 'spark', label: 'Spark', bg: '#c2410c', fg: '#fff7ed',
+        shapes: [
+            { tag: 'path', d: 'm12 3 1.5 5.2L19 10l-5.5 1.8L12 17l-1.5-5.2L5 10l5.5-1.8Z' },
+            { tag: 'path', d: 'm18.5 15 .7 2.2 2.3.8-2.3.8-.7 2.2-.7-2.2-2.3-.8 2.3-.8Z' },
+        ],
+    },
+]);
+const BY_ID = new Map(IDENTITY_PRESETS.map((preset) => [preset.id, preset]));
+const ICONIFY_ID = /^[a-z0-9-]+[:/][a-z0-9-]+$/i;
+const ALIASES = new Map([
+    ['rocket', 'mdi:rocket-launch'],
+    ['mdi/rocket-launch', 'mdi:rocket-launch'],
+    ['layers', 'gateway'],
+    ['default', 'spexcode'],
+]);
+export const IDENTITY_PRESET_IDS = Object.freeze(IDENTITY_PRESETS.map((preset) => preset.id));
+export function resolvedIdentityIcon(value, fallback = DEFAULT_PROJECT_ICON) {
+    const raw = typeof value === 'string' ? value.trim() : '';
+    const id = ALIASES.get(raw) || raw;
+    return id || fallback;
+}
+export function identityPreset(value) {
+    const raw = typeof value === 'string' ? value.trim() : '';
+    return BY_ID.get(ALIASES.get(raw) || raw) || null;
+}
+export function isIconifyIcon(value) {
+    return ICONIFY_ID.test(typeof value === 'string' ? value.trim() : '');
+}
+export function requireIdentityChoice(value) {
+    const raw = typeof value === 'string' ? value.trim() : '';
+    const id = ALIASES.get(raw) || raw;
+    if (BY_ID.has(id))
+        return id;
+    if (isIconifyIcon(id))
+        return id.replace('/', ':');
+    throw new Error(`unknown identity icon '${raw}' (choose a preset or Iconify prefix:name)`);
+}
+function attrs(shape) {
+    return Object.entries(shape).filter(([key]) => key !== 'tag')
+        .map(([key, value]) => `${key === 'className' ? 'class' : key}="${String(value).replaceAll('&', '&').replaceAll('"', '"')}"`).join(' ');
+}
+export function identitySvg(value, fallback = DEFAULT_PROJECT_ICON) {
+    const preset = identityPreset(value) || identityPreset(fallback);
+    const geometry = preset.shapes.map((shape) => `<${shape.tag} ${attrs(shape)}/>`).join('');
+    return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><rect x="1" y="1" width="22" height="22" rx="5" fill="${preset.bg}"/><g fill="none" stroke="${preset.fg}" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round">${geometry}</g></svg>`;
+}
+export function identityFaviconHref(value, fallback = DEFAULT_PROJECT_ICON) {
+    const resolved = resolvedIdentityIcon(value, fallback);
+    if (identityPreset(resolved))
+        return `data:image/svg+xml,${encodeURIComponent(identitySvg(resolved, fallback))}`;
+    if (/^https?:\/\//.test(resolved))
+        return resolved;
+    if (isIconifyIcon(resolved))
+        return `https://api.iconify.design/${resolved.replace(':', '/')}.svg`;
+    const glyph = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100"><text x="50" y=".86em" font-size="82" text-anchor="middle">${resolved.replaceAll('&', '&amp;').replaceAll('<', '&lt;')}</text></svg>`;
+    return `data:image/svg+xml,${encodeURIComponent(glyph)}`;
+}

package/dist/index.d.ts

@@ -0,0 +1,45 @@
+export declare function readSpecs(root: string): Promise<{
+    id: string;
+    parent: string | null;
+    path: string;
+    title: string;
+    status: import("./specs.js").DerivedStatus;
+    fmStatus: string | null;
+    session: string | null;
+    hue: number;
+    desc: string;
+    code: string[];
+    codeEntries: import("./anchors.js").RelationEntry[];
+    codeScoped: import("./anchors.js").RelationEntry[];
+    related: string[];
+    relatedEntries: import("./anchors.js").RelationEntry[];
+    relatedScoped: import("./anchors.js").RelationEntry[];
+    relationProblems: string[];
+    version: number;
+    reason: string;
+    lastEdited: string | null;
+    drift: number;
+    driftFiles: {
+        file: string;
+        behind: number;
+    }[];
+    relatedDriftFiles: {
+        file: string;
+        behind: number;
+    }[];
+    body: string;
+    parts: import("./specs.js").SpecParts | null;
+}[]>;
+export * from './anchors.js';
+export * from './git.js';
+export * from './graph.js';
+export * from './graphDelta.js';
+export * from './harness-identity.js';
+export * from './layout.js';
+export * from './process-identity.js';
+export * from './project-identity.js';
+export * from './project-store.js';
+export * from './resilience.js';
+export * from './reviewSnapshot.js';
+export * from './root-lru.js';
+export * from './specs.js';

package/dist/index.js

@@ -0,0 +1,19 @@
+import { sourceIndexesFull } from './git.js';
+import { loadSpecs } from './specs.js';
+export async function readSpecs(root) {
+    const [history, drift] = await sourceIndexesFull(root);
+    return loadSpecs(root, { history, drift });
+}
+export * from './anchors.js';
+export * from './git.js';
+export * from './graph.js';
+export * from './graphDelta.js';
+export * from './harness-identity.js';
+export * from './layout.js';
+export * from './process-identity.js';
+export * from './project-identity.js';
+export * from './project-store.js';
+export * from './resilience.js';
+export * from './reviewSnapshot.js';
+export * from './root-lru.js';
+export * from './specs.js';

package/dist/layout.d.ts

@@ -0,0 +1,183 @@
+import { type NodeOp } from './git.js';
+import { type HarnessId } from './harness-identity.js';
+export type Config = {
+    main?: string;
+    mainBranch?: string;
+    branchPrefix?: string;
+    preset?: string;
+    render?: string;
+    private?: boolean;
+    harnesses?: (string | {
+        plugin?: string;
+    })[];
+    dashboard?: {
+        apiUrl?: string;
+        title?: string;
+        icon?: string;
+        showHeadlessLaunchers?: boolean;
+    };
+    uploads?: {
+        maxBytes?: number;
+        chunkBytes?: number;
+        concurrency?: number;
+        requestTimeoutMs?: number;
+        retryLimit?: number;
+        retryDelayMs?: number;
+        incompleteTtlMs?: number;
+        cleanupIntervalMs?: number;
+        minFreeBytes?: number;
+        evidenceMaxBytes?: number;
+    };
+    sessions?: {
+        maxActive?: number;
+        launchers?: {
+            [name: string]: {
+                harness?: HarnessId;
+                cmd: string;
+            };
+        };
+        defaultLauncher?: string;
+    };
+    resources?: {
+        sessionRssMiB?: number;
+        backendRssMiB?: number;
+        idleCpuPercent?: number;
+        sampleMs?: number;
+        reportIntervalMs?: number;
+    };
+    serve?: {
+        public?: {
+            enabled?: boolean;
+            http?: boolean;
+            tls?: {
+                cert?: string;
+                key?: string;
+            };
+        };
+    };
+    issues?: {
+        enabled?: boolean;
+    };
+    forge?: {
+        host?: string;
+    };
+};
+type Convention = Required<Omit<Config, 'dashboard' | 'uploads' | 'sessions' | 'resources' | 'serve' | 'harnesses' | 'preset' | 'issues' | 'forge' | 'private' | 'render'>>;
+export type Worktree = {
+    path: string;
+    branch: string | null;
+    node: string | null;
+    session: string | null;
+    status: string | null;
+    isMain: boolean;
+    liveness?: 'offline' | 'unknown';
+    ops: NodeOp[];
+};
+export type Layout = {
+    main: string;
+    convention: Convention;
+    worktrees: Worktree[];
+};
+export declare function readJsonConfig(p: string): any;
+export declare function readConfig(root: string): Config;
+export type UploadPolicy = Required<NonNullable<Config['uploads']>>;
+export declare const templateConfigPath: string;
+export declare function uploadPolicyDefaults(): UploadPolicy;
+export declare function readUploadPolicy(root: string): UploadPolicy;
+export declare function gitCommonDir(): string;
+export declare function mainBranch(): string;
+export declare function mainCheckout(proj?: string): string;
+export declare function mainRoot(proj?: string): string;
+export declare function runtimeRoot(proj?: string): string;
+export declare function treeSlotDir(wt: string): string;
+export declare function sessionsRoot(): string;
+export declare function sessionStoreDir(id: string): string;
+export declare function sessionRecordPath(id: string): string;
+export declare function sessionArtifactPath(id: string, name: string): string;
+export type RawRecord = {
+    session_id: string;
+    governed: boolean;
+    worktree_path: string;
+    branch: string | null;
+    node: string | null;
+    title: string | null;
+    name: string | null;
+    parent?: string | null;
+    status: string;
+    proposal: string | null;
+    merges: number;
+    note: string | null;
+    sortkey: number | null;
+    createdAt: number;
+    harness?: string;
+    harness_session_id?: string;
+    stopped?: boolean;
+    archived?: boolean;
+    cold_proof?: string;
+    adapter_recovery?: string;
+    launcher?: string;
+    launch_cmd?: string;
+    create_request_id?: string;
+    create_payload_hash?: string;
+    zcode_child_session_ids?: string[];
+    base?: string;
+    launch_readiness_pending?: '' | RawLaunchReadinessPending;
+};
+export declare const SESSION_LIFECYCLES: readonly ["active", "idle", "awaiting", "parked", "error", "asking", "queued"];
+export declare const SESSION_PROPOSALS: readonly ["merge", "nothing", "close"];
+export type SessionLifecycle = typeof SESSION_LIFECYCLES[number];
+export type SessionProposal = typeof SESSION_PROPOSALS[number];
+export declare const isSessionLifecycle: (value: unknown) => value is SessionLifecycle;
+export declare const isSessionProposal: (value: unknown) => value is SessionProposal;
+export type RawLaunchReadinessOriginal = {
+    status: string;
+    proposal: string | null;
+    note: string | null;
+    stopped: boolean;
+    archived: boolean;
+    cold_proof: string | null;
+    adapter_recovery: string | null;
+};
+export type RawLaunchReadinessPending = {
+    version: 1;
+    startedAt: number;
+    original: RawLaunchReadinessOriginal;
+};
+export declare function rawLaunchReadinessOriginal(raw: RawRecord): RawLaunchReadinessOriginal | null;
+export declare function envSessionId(): string | null;
+export type RecordEntry = {
+    kind: 'ok';
+    raw: RawRecord;
+} | {
+    kind: 'absent';
+} | {
+    kind: 'corrupt';
+    path: string;
+    error: string;
+};
+export type PublicRecordEntry = {
+    kind: 'ok';
+    raw: RawRecord;
+    liveness: 'offline' | null;
+} | {
+    kind: 'absent';
+} | {
+    kind: 'corrupt';
+    sessionId: string;
+    governed: boolean | null;
+    path: string;
+    error: string;
+    liveness: 'unknown';
+};
+export declare function readRecordEntry(id: string): RecordEntry;
+export declare function projectPublicRecordEntry(id: string, entry: RecordEntry): PublicRecordEntry;
+export declare function readPublicRecordEntry(id: string): PublicRecordEntry;
+export declare function readRawRecord(id: string): RawRecord | null;
+export declare function readAliasedRawRecord(id: string): RawRecord | null;
+export declare function readAliasedRecordEntry(id: string): RecordEntry;
+export declare function listSessionIds(): string[];
+export declare function sessionBranchIndex(): Map<string, string>;
+export declare function resolveLayout(options?: {
+    activeSessionIds?: readonly string[];
+}): Promise<Layout>;
+export {};