@phyzess/pappra 0.0.0-stage → 0.1.0-beta.1

package/dist/schemas/machine.js

@@ -0,0 +1,96 @@
+import { isAbsolute } from 'node:path';
+import { z } from 'zod';
+import { createDiagnostic, pointer } from './diagnostics.js';
+import { diagnosticCodes } from './errors.js';
+export const MACHINE_SCHEMA = 'pappra/machine/1';
+const identifierSchema = z
+    .string()
+    .min(1)
+    .max(64)
+    .regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/);
+export const hostSchema = z.enum(['pi', 'codex', 'claude']);
+export const externalRepositoryMappingSchema = z.strictObject({
+    id: identifierSchema,
+    path: z.string().min(1).max(4096),
+});
+export const runtimeLocationSchema = z.strictObject({
+    version: z.string().min(1).max(128),
+    executable: z.string().min(1).max(4096),
+    verifiedAt: z.iso.datetime({ offset: true }),
+});
+export const machineConfigSchema = z.strictObject({
+    schema: z.literal(MACHINE_SCHEMA),
+    workspaceRealpath: z.string().min(1).max(4096),
+    checkoutId: z.uuid(),
+    externalRepositories: z.array(externalRepositoryMappingSchema).max(128),
+    selectedHosts: z.array(hostSchema).max(16),
+    runtime: runtimeLocationSchema.nullable(),
+});
+export function validateMachineConfigSemantics(config, options) {
+    const { configPath } = options;
+    const diagnostics = [];
+    const externalIds = new Map();
+    if (!isAbsolute(config.workspaceRealpath)) {
+        diagnostics.push(createDiagnostic({
+            code: diagnosticCodes.configPathAbsolute,
+            severity: 'error',
+            message: 'workspaceRealpath must be an absolute host path.',
+            source: configPath,
+            pointer: pointer('workspaceRealpath'),
+            hint: 'Write the real path of this checkout; machine.json is not shared across machines.',
+        }));
+    }
+    config.externalRepositories.forEach((mapping, index) => {
+        const first = externalIds.get(mapping.id);
+        if (first !== undefined) {
+            diagnostics.push(createDiagnostic({
+                code: diagnosticCodes.machineExternalDuplicate,
+                severity: 'error',
+                message: `External repository id "${mapping.id}" is already mapped by externalRepositories[${first}].`,
+                source: configPath,
+                pointer: pointer('externalRepositories', index, 'id'),
+                hint: 'Keep exactly one local mapping per logical external repository id.',
+            }));
+        }
+        else {
+            externalIds.set(mapping.id, index);
+        }
+        if (!isAbsolute(mapping.path) || mapping.path.includes('\0')) {
+            diagnostics.push(createDiagnostic({
+                code: diagnosticCodes.machineExternalPathInvalid,
+                severity: 'error',
+                message: `External repository "${mapping.id}" must map to an absolute host path.`,
+                source: configPath,
+                pointer: pointer('externalRepositories', index, 'path'),
+                hint: 'Shared workspace.json stores only external:<id>; the absolute path stays in local machine.json.',
+            }));
+        }
+    });
+    const seenHosts = new Set();
+    for (const [index, host] of config.selectedHosts.entries()) {
+        if (seenHosts.has(host)) {
+            diagnostics.push(createDiagnostic({
+                code: diagnosticCodes.configSchemaInvalid,
+                severity: 'warning',
+                message: `Host "${host}" is selected more than once.`,
+                source: configPath,
+                pointer: pointer('selectedHosts', index),
+                hint: 'Remove the duplicate host entry.',
+            }));
+        }
+        seenHosts.add(host);
+    }
+    if (config.runtime !== null) {
+        if (!isAbsolute(config.runtime.executable)) {
+            diagnostics.push(createDiagnostic({
+                code: diagnosticCodes.configPathAbsolute,
+                severity: 'error',
+                message: 'The verified runtime executable must be an absolute host path.',
+                source: configPath,
+                pointer: pointer('runtime', 'executable'),
+                hint: 'Record the fixed runtime path created by the installer.',
+            }));
+        }
+    }
+    return diagnostics;
+}

package/dist/schemas/outcome.d.ts

@@ -0,0 +1,23 @@
+import type { DiagnosticCode } from './errors.js';
+/** Expected rejection; unexpected exceptions are converted at application boundaries. */
+export type Outcome<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly code: DiagnosticCode;
+    readonly message: string;
+    readonly retryable: boolean;
+    readonly nextAction: string | null;
+};
+export interface FailureOptions {
+    readonly retryable?: boolean;
+    readonly nextAction?: string | null;
+    readonly cause?: unknown;
+}
+export type Failure = Extract<Outcome<never>, {
+    readonly ok: false;
+}>;
+export declare function succeeded<T>(value: T): Outcome<T>;
+export declare function failed(code: DiagnosticCode, message: string, options?: FailureOptions): Failure;
+export declare function errorMessage(error: unknown): string;

package/dist/schemas/outcome.js

@@ -0,0 +1,17 @@
+export function succeeded(value) {
+    return { ok: true, value };
+}
+export function failed(code, message, options = {}) {
+    const failure = {
+        ok: false,
+        code,
+        message,
+        retryable: options.retryable ?? false,
+        nextAction: options.nextAction ?? null,
+        ...(options.cause === undefined ? {} : { cause: options.cause }),
+    };
+    return failure;
+}
+export function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/schemas/paths.d.ts

@@ -0,0 +1,19 @@
+export declare const externalRepositoryPrefix = "external:";
+export declare function hasNul(value: string): boolean;
+/**
+ * Shared workspace paths are portable and relative: forward slashes only, no
+ * drive or UNC prefix, and no lexical escape above the configuration root.
+ */
+export declare function isPortableRelativePath(value: string): boolean;
+/** Normalizes a portable relative path to a stable, slash-separated form. */
+export declare function normalizePortableRelativePath(value: string): string;
+/** Resolves a portable relative path against a host-native root. */
+export declare function resolvePortableRelativePath(root: string, value: string): string;
+/** Returns a slash-separated path relative to root, or null when outside. */
+export declare function toWorkspaceRelativePath(root: string, target: string): string | null;
+export declare function isPathInside(root: string, target: string): boolean;
+/** Compares already-normalized paths; Windows comparisons are case-insensitive. */
+export declare function samePath(left: string, right: string): boolean;
+export declare function isExternalRepositoryPath(value: string): boolean;
+/** Returns the logical ID in `external:<id>`, or null when malformed. */
+export declare function externalRepositoryId(value: string): string | null;

package/dist/schemas/paths.js

@@ -0,0 +1,63 @@
+import { isAbsolute, posix, relative, resolve, sep, win32 } from 'node:path';
+export const externalRepositoryPrefix = 'external:';
+const portableIdentifier = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+export function hasNul(value) {
+    return value.includes('\0');
+}
+/**
+ * Shared workspace paths are portable and relative: forward slashes only, no
+ * drive or UNC prefix, and no lexical escape above the configuration root.
+ */
+export function isPortableRelativePath(value) {
+    if (value.length === 0 || hasNul(value) || value.includes('\\'))
+        return false;
+    if (posix.isAbsolute(value) || win32.isAbsolute(value))
+        return false;
+    const normalized = posix.normalize(value);
+    return (normalized !== '..' &&
+        !normalized.startsWith('../') &&
+        !normalized.startsWith('/'));
+}
+/** Normalizes a portable relative path to a stable, slash-separated form. */
+export function normalizePortableRelativePath(value) {
+    const normalized = posix.normalize(value);
+    if (normalized === '.')
+        return '.';
+    return normalized.replace(/\/+$/, '');
+}
+/** Resolves a portable relative path against a host-native root. */
+export function resolvePortableRelativePath(root, value) {
+    const normalized = normalizePortableRelativePath(value);
+    if (normalized === '.')
+        return resolve(root);
+    return resolve(root, ...normalized.split('/'));
+}
+/** Returns a slash-separated path relative to root, or null when outside. */
+export function toWorkspaceRelativePath(root, target) {
+    if (!isPathInside(root, target))
+        return null;
+    const path = relative(root, target);
+    return path === '' ? '.' : path.split(sep).join('/');
+}
+export function isPathInside(root, target) {
+    const path = relative(root, target);
+    return (path === '' ||
+        (path !== '..' && !path.startsWith(`..${sep}`) && !isAbsolute(path)));
+}
+/** Compares already-normalized paths; Windows comparisons are case-insensitive. */
+export function samePath(left, right) {
+    if (process.platform === 'win32') {
+        return left.toLowerCase() === right.toLowerCase();
+    }
+    return left === right;
+}
+export function isExternalRepositoryPath(value) {
+    return value.startsWith(externalRepositoryPrefix);
+}
+/** Returns the logical ID in `external:<id>`, or null when malformed. */
+export function externalRepositoryId(value) {
+    if (!isExternalRepositoryPath(value))
+        return null;
+    const id = value.slice(externalRepositoryPrefix.length);
+    return portableIdentifier.test(id) ? id : null;
+}

package/dist/schemas/workspace.d.ts

@@ -0,0 +1,120 @@
+import { z } from 'zod';
+import { type Diagnostic } from './diagnostics.js';
+export declare const WORKSPACE_SCHEMA = "pappra/workspace/1";
+export declare const repositoryAccessSchema: z.ZodEnum<{
+    read: "read";
+    write: "write";
+}>;
+export declare const codeGraphSchema: z.ZodEnum<{
+    codegraph: "codegraph";
+    none: "none";
+}>;
+export declare const symbolProviderSchema: z.ZodEnum<{
+    auto: "auto";
+    none: "none";
+    serena: "serena";
+}>;
+export declare const indexPreparationSchema: z.ZodEnum<{
+    manual: "manual";
+    "on-demand": "on-demand";
+}>;
+export declare const taskVisibilitySchema: z.ZodEnum<{
+    private: "private";
+    shared: "shared";
+}>;
+export declare const workspaceRepositorySchema: z.ZodObject<{
+    id: z.ZodString;
+    path: z.ZodString;
+    access: z.ZodEnum<{
+        read: "read";
+        write: "write";
+    }>;
+}, z.core.$strict>;
+export declare const workspaceKnowledgeSchema: z.ZodObject<{
+    sources: z.ZodArray<z.ZodString>;
+    newDocuments: z.ZodString;
+    taskVisibility: z.ZodEnum<{
+        private: "private";
+        shared: "shared";
+    }>;
+}, z.core.$strict>;
+export declare const workspaceCodeSchema: z.ZodObject<{
+    graph: z.ZodEnum<{
+        codegraph: "codegraph";
+        none: "none";
+    }>;
+    symbols: z.ZodEnum<{
+        auto: "auto";
+        none: "none";
+        serena: "serena";
+    }>;
+    prepare: z.ZodEnum<{
+        manual: "manual";
+        "on-demand": "on-demand";
+    }>;
+}, z.core.$strict>;
+export declare const workspaceValidationSchema: z.ZodObject<{
+    id: z.ZodString;
+    repositoryId: z.ZodString;
+    executable: z.ZodString;
+    args: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export declare const workspaceConfigSchema: z.ZodObject<{
+    schema: z.ZodLiteral<"pappra/workspace/1">;
+    workspaceId: z.ZodUUID;
+    name: z.ZodString;
+    runtimeVersion: z.ZodString;
+    repositories: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        path: z.ZodString;
+        access: z.ZodEnum<{
+            read: "read";
+            write: "write";
+        }>;
+    }, z.core.$strict>>;
+    knowledge: z.ZodObject<{
+        sources: z.ZodArray<z.ZodString>;
+        newDocuments: z.ZodString;
+        taskVisibility: z.ZodEnum<{
+            private: "private";
+            shared: "shared";
+        }>;
+    }, z.core.$strict>;
+    code: z.ZodObject<{
+        graph: z.ZodEnum<{
+            codegraph: "codegraph";
+            none: "none";
+        }>;
+        symbols: z.ZodEnum<{
+            auto: "auto";
+            none: "none";
+            serena: "serena";
+        }>;
+        prepare: z.ZodEnum<{
+            manual: "manual";
+            "on-demand": "on-demand";
+        }>;
+    }, z.core.$strict>;
+    validation: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        repositoryId: z.ZodString;
+        executable: z.ZodString;
+        args: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
+    excludes: z.ZodArray<z.ZodString>;
+    extensions: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strict>;
+export type WorkspaceConfig = z.infer<typeof workspaceConfigSchema>;
+export type WorkspaceRepository = z.infer<typeof workspaceRepositorySchema>;
+export type WorkspaceValidation = z.infer<typeof workspaceValidationSchema>;
+export type RepositoryAccess = z.infer<typeof repositoryAccessSchema>;
+export interface WorkspaceConfigSemanticOptions {
+    readonly configPath: string;
+}
+/**
+ * Applies rules that cannot be expressed by the structural schema alone.
+ * The caller must only use the value when no returned diagnostic is an error.
+ */
+export declare function validateWorkspaceConfigSemantics(config: WorkspaceConfig, options: WorkspaceConfigSemanticOptions): readonly Diagnostic[];
+/** Normalizes config-declared excludes for prefix comparisons. */
+export declare function normalizedExcludes(config: WorkspaceConfig): readonly string[];

package/dist/schemas/workspace.js

@@ -0,0 +1,201 @@
+import { z } from 'zod';
+import { createDiagnostic, pointer } from './diagnostics.js';
+import { diagnosticCodes } from './errors.js';
+import { externalRepositoryId, isExternalRepositoryPath, isPortableRelativePath, normalizePortableRelativePath, } from './paths.js';
+export const WORKSPACE_SCHEMA = 'pappra/workspace/1';
+const identifierSchema = z
+    .string()
+    .min(1)
+    .max(64)
+    .regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/, 'Use a letter or digit followed by letters, digits, dot, underscore or dash.');
+const portablePathSchema = z.string().min(1).max(2048);
+const executableSchema = z
+    .string()
+    .min(1)
+    .max(4096)
+    .refine((value) => !value.includes('\0'), 'NUL is not allowed.');
+const argumentSchema = z
+    .string()
+    .max(4096)
+    .refine((value) => !value.includes('\0'), 'NUL is not allowed.');
+export const repositoryAccessSchema = z.enum(['read', 'write']);
+export const codeGraphSchema = z.enum(['codegraph', 'none']);
+export const symbolProviderSchema = z.enum(['auto', 'serena', 'none']);
+export const indexPreparationSchema = z.enum(['on-demand', 'manual']);
+export const taskVisibilitySchema = z.enum(['private', 'shared']);
+export const workspaceRepositorySchema = z.strictObject({
+    id: identifierSchema,
+    path: portablePathSchema,
+    access: repositoryAccessSchema,
+});
+export const workspaceKnowledgeSchema = z.strictObject({
+    sources: z.array(portablePathSchema).max(128),
+    newDocuments: portablePathSchema,
+    taskVisibility: taskVisibilitySchema,
+});
+export const workspaceCodeSchema = z.strictObject({
+    graph: codeGraphSchema,
+    symbols: symbolProviderSchema,
+    prepare: indexPreparationSchema,
+});
+export const workspaceValidationSchema = z.strictObject({
+    id: identifierSchema,
+    repositoryId: identifierSchema,
+    executable: executableSchema,
+    args: z.array(argumentSchema).max(256),
+});
+export const workspaceConfigSchema = z.strictObject({
+    schema: z.literal(WORKSPACE_SCHEMA),
+    workspaceId: z.uuid(),
+    name: z.string().min(1).max(200),
+    runtimeVersion: z.string().min(1).max(128),
+    repositories: z.array(workspaceRepositorySchema).max(128),
+    knowledge: workspaceKnowledgeSchema,
+    code: workspaceCodeSchema,
+    validation: z.array(workspaceValidationSchema).max(128),
+    excludes: z.array(portablePathSchema).max(128),
+    extensions: z.record(z.string().min(1).max(128), z.unknown()),
+});
+function pathDiagnostic(value, source, fieldPointer, label) {
+    const hint = 'Use a workspace-relative path such as "docs" or "repos/app".';
+    if (value.includes('\0') || value.includes('\\')) {
+        return createDiagnostic({
+            code: diagnosticCodes.configPathInvalid,
+            severity: 'error',
+            message: `${label} must use forward slashes and must not contain NUL or backslashes.`,
+            source,
+            pointer: fieldPointer,
+            hint,
+        });
+    }
+    if (value.startsWith('/') ||
+        /^[A-Za-z]:/.test(value) ||
+        value.startsWith('\\\\')) {
+        return createDiagnostic({
+            code: diagnosticCodes.configPathAbsolute,
+            severity: 'error',
+            message: `${label} must be relative to the workspace root, not absolute.`,
+            source,
+            pointer: fieldPointer,
+            hint,
+        });
+    }
+    if (!isPortableRelativePath(value)) {
+        return createDiagnostic({
+            code: diagnosticCodes.configPathEscapesRoot,
+            severity: 'error',
+            message: `${label} escapes the workspace root.`,
+            source,
+            pointer: fieldPointer,
+            hint,
+        });
+    }
+    return null;
+}
+/**
+ * Applies rules that cannot be expressed by the structural schema alone.
+ * The caller must only use the value when no returned diagnostic is an error.
+ */
+export function validateWorkspaceConfigSemantics(config, options) {
+    const { configPath } = options;
+    const diagnostics = [];
+    const repositoryIds = new Map();
+    const validationIds = new Map();
+    config.repositories.forEach((repository, index) => {
+        const first = repositoryIds.get(repository.id);
+        if (first !== undefined) {
+            diagnostics.push(createDiagnostic({
+                code: diagnosticCodes.configDuplicateRepositoryId,
+                severity: 'error',
+                message: `Repository id "${repository.id}" is already used by repositories[${first}].`,
+                source: configPath,
+                pointer: pointer('repositories', index, 'id'),
+                hint: 'Give every repository a unique id within the workspace.',
+            }));
+        }
+        else {
+            repositoryIds.set(repository.id, index);
+        }
+        if (isExternalRepositoryPath(repository.path)) {
+            if (externalRepositoryId(repository.path) === null) {
+                diagnostics.push(createDiagnostic({
+                    code: diagnosticCodes.configPathInvalid,
+                    severity: 'error',
+                    message: `Repository path "${repository.path}" is not a valid external:<id> reference.`,
+                    source: configPath,
+                    pointer: pointer('repositories', index, 'path'),
+                    hint: 'Use external:<logical-id> and declare the absolute location in .pappra/local/machine.json.',
+                }));
+            }
+        }
+        else {
+            const pathIssue = pathDiagnostic(repository.path, configPath, pointer('repositories', index, 'path'), `Repository "${repository.id}" path`);
+            if (pathIssue !== null)
+                diagnostics.push(pathIssue);
+        }
+    });
+    config.validation.forEach((validation, index) => {
+        const first = validationIds.get(validation.id);
+        if (first !== undefined) {
+            diagnostics.push(createDiagnostic({
+                code: diagnosticCodes.configDuplicateValidationId,
+                severity: 'error',
+                message: `Validation id "${validation.id}" is already used by validation[${first}].`,
+                source: configPath,
+                pointer: pointer('validation', index, 'id'),
+                hint: 'Give every validation command a unique id.',
+            }));
+        }
+        else {
+            validationIds.set(validation.id, index);
+        }
+        if (!repositoryIds.has(validation.repositoryId)) {
+            diagnostics.push(createDiagnostic({
+                code: diagnosticCodes.configUnknownRepository,
+                severity: 'error',
+                message: `Validation "${validation.id}" refers to unknown repository "${validation.repositoryId}".`,
+                source: configPath,
+                pointer: pointer('validation', index, 'repositoryId'),
+                hint: 'Declare the repository first or correct the repositoryId.',
+            }));
+        }
+    });
+    config.knowledge.sources.forEach((source, index) => {
+        const pathIssue = pathDiagnostic(source, configPath, pointer('knowledge', 'sources', index), 'Knowledge source');
+        if (pathIssue !== null)
+            diagnostics.push(pathIssue);
+        if (isExternalRepositoryPath(source)) {
+            diagnostics.push(createDiagnostic({
+                code: diagnosticCodes.configPathInvalid,
+                severity: 'error',
+                message: 'Knowledge sources must stay inside the workspace; external: references are only valid for repositories.',
+                source: configPath,
+                pointer: pointer('knowledge', 'sources', index),
+                hint: 'Copy no external knowledge; declare an external repository and read its documentation in place.',
+            }));
+        }
+    });
+    const newDocumentsIssue = pathDiagnostic(config.knowledge.newDocuments, configPath, pointer('knowledge', 'newDocuments'), 'New document directory');
+    if (newDocumentsIssue !== null)
+        diagnostics.push(newDocumentsIssue);
+    config.excludes.forEach((exclude, index) => {
+        const pathIssue = pathDiagnostic(exclude, configPath, pointer('excludes', index), 'Exclude entry');
+        if (pathIssue !== null)
+            diagnostics.push(pathIssue);
+        if (/[*?[\]{}]/.test(exclude)) {
+            diagnostics.push(createDiagnostic({
+                code: diagnosticCodes.configGlobNotSupported,
+                severity: 'error',
+                message: `Exclude entry "${exclude}" contains glob metacharacters.`,
+                source: configPath,
+                pointer: pointer('excludes', index),
+                hint: 'Use literal workspace-relative file or directory prefixes; glob expansion is not part of schema version 1.',
+            }));
+        }
+    });
+    return diagnostics;
+}
+/** Normalizes config-declared excludes for prefix comparisons. */
+export function normalizedExcludes(config) {
+    return config.excludes.map((entry) => normalizePortableRelativePath(entry));
+}

package/dist/workspace/config-file.d.ts

@@ -0,0 +1,36 @@
+import type { z } from 'zod';
+import type { Diagnostic, DiagnosticSeverity } from '../schemas/diagnostics.js';
+import { type Outcome } from '../schemas/outcome.js';
+export interface ConfigFileInspection<T> {
+    /** The path the caller asked to inspect (not silently replaced by a symlink target). */
+    readonly path: string;
+    readonly exists: boolean;
+    readonly digest: string | null;
+    readonly size: number | null;
+    readonly value: T | null;
+    readonly diagnostics: readonly Diagnostic[];
+}
+export interface ConfigFileMissingPolicy {
+    readonly severity: DiagnosticSeverity;
+    readonly message: string;
+    readonly hint: string;
+}
+export interface InspectConfigFileOptions<T> {
+    readonly path: string;
+    readonly schemaName: string;
+    readonly schema: z.ZodType<T>;
+    readonly missing: ConfigFileMissingPolicy;
+    /** When set, the real path of the file must stay inside this real directory. */
+    readonly containmentRoot?: string;
+    readonly maxBytes?: number;
+    readonly semantic?: (value: T) => readonly Diagnostic[];
+}
+/**
+ * Reads, decodes, validates, and semantically checks one strict JSON
+ * configuration file. Missing configuration is reported instead of defaulted.
+ */
+export declare function inspectConfigFile<T>(options: InspectConfigFileOptions<T>): Promise<ConfigFileInspection<T>>;
+/** Converts an inspection into a convenience result for callers that fail closed. */
+export declare function requireConfig<T>(inspection: ConfigFileInspection<T>): Outcome<T>;
+/** Joins a workspace-relative configuration path without normalizing above root. */
+export declare function workspaceConfigPath(root: string): string;