@dev-sergeev/datalab-kit 0.1.2 → 0.1.4

package/node_modules/@zigai/pi-extension-settings/dist/settings-transaction.js

@@ -0,0 +1,202 @@
+import { mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import lockfile from "proper-lockfile";
+import { readTextIfPresentAsync, writeTextAtomicallyAsync } from "./file-system.js";
+import { cloneJson, formatJson, isJsonObject, JsonValueSchema, } from "./json-value.js";
+import { Value } from "./typebox-runtime.js";
+import { createSettingsDocument, createSettingsFileSchema } from "./schema-document.js";
+import { applySettingsLayer, parseSettingsLayer, settingsValidationIssues, } from "./settings-layer.js";
+import { mergeSettings } from "./settings-merge.js";
+import { createSettingsRevision } from "./settings-revision.js";
+class SettingsPersistenceError extends Error {
+    constructor(cause) {
+        super("The settings transaction could not access persistent storage.", { cause });
+    }
+}
+async function persistently(operation) {
+    try {
+        return await operation();
+    }
+    catch (cause) {
+        throw new SettingsPersistenceError(cause);
+    }
+}
+function typedSettingsLayer(schema, value) {
+    return isJsonObject(value) && !("$schema" in value) && Value.Check(schema, value);
+}
+function parseExistingLayer(path, scope, text, layerSchema) {
+    if (text === undefined) {
+        return {
+            status: "valid",
+            settings: {},
+            schemaReference: undefined,
+        };
+    }
+    const parsedLayer = parseSettingsLayer(path, scope, text, layerSchema);
+    if (parsedLayer.settings === undefined) {
+        return { status: "invalid", diagnostics: parsedLayer.diagnostics };
+    }
+    return {
+        status: "valid",
+        settings: parsedLayer.settings,
+        schemaReference: parsedLayer.schemaReference,
+    };
+}
+function invalidExisting(diagnostics) {
+    return {
+        status: "invalid-existing",
+        message: diagnostics[0]?.message ?? "The existing settings are invalid.",
+        diagnostics,
+    };
+}
+function invalidUpdate(message, issues) {
+    return { status: "invalid-update", message, issues };
+}
+async function withInterprocessLocks(paths, operation, index = 0) {
+    const path = paths[index];
+    if (path === undefined)
+        return operation();
+    await persistently(() => mkdir(dirname(path), { recursive: true }));
+    const release = await persistently(() => lockfile.lock(path, {
+        realpath: false,
+        retries: {
+            retries: 20,
+            factor: 1.25,
+            minTimeout: 10,
+            maxTimeout: 100,
+            randomize: true,
+        },
+    }));
+    try {
+        return await withInterprocessLocks(paths, operation, index + 1);
+    }
+    finally {
+        await persistently(release);
+    }
+}
+async function runSettingsTransaction(definition, options) {
+    const layerSchema = createSettingsFileSchema(definition);
+    const expectedSchema = formatJson(layerSchema);
+    const installedSchema = await persistently(() => readTextIfPresentAsync(options.paths.global.schemaPath));
+    if (installedSchema !== expectedSchema) {
+        return {
+            status: "conflict",
+            reason: "schema-changed",
+            message: "The installed settings schema changed; reload the extension before saving.",
+        };
+    }
+    const globalText = await persistently(() => readTextIfPresentAsync(options.paths.global.configPath));
+    const projectText = options.scope === "project"
+        ? await persistently(() => readTextIfPresentAsync(options.paths.project.configPath))
+        : undefined;
+    const revision = options.scope === "global"
+        ? createSettingsRevision(globalText)
+        : createSettingsRevision(globalText, projectText);
+    if (options.expectedRevision !== undefined && options.expectedRevision !== revision) {
+        return {
+            status: "conflict",
+            reason: "settings-changed",
+            message: "The settings changed after they were loaded; reload before saving.",
+        };
+    }
+    const globalResult = parseExistingLayer(options.paths.global.configPath, "global", globalText, layerSchema);
+    if (globalResult.status === "invalid")
+        return invalidExisting(globalResult.diagnostics);
+    const globalApplied = applySettingsLayer(definition.schema, definition.defaultSettings, globalResult, options.paths.global.configPath, "global");
+    if (globalApplied.diagnostic !== undefined) {
+        return invalidExisting([globalApplied.diagnostic]);
+    }
+    let currentLayer = globalResult;
+    let validationBase = definition.defaultSettings;
+    if (options.scope === "project") {
+        const projectResult = parseExistingLayer(options.paths.project.configPath, "project", projectText, layerSchema);
+        if (projectResult.status === "invalid")
+            return invalidExisting(projectResult.diagnostics);
+        const projectApplied = applySettingsLayer(definition.schema, globalApplied.settings, projectResult, options.paths.project.configPath, "project");
+        if (projectApplied.diagnostic !== undefined) {
+            return invalidExisting([projectApplied.diagnostic]);
+        }
+        currentLayer = projectResult;
+        validationBase = globalApplied.settings;
+    }
+    const currentForUpdate = cloneJson(currentLayer.settings);
+    if (!typedSettingsLayer(layerSchema, currentForUpdate)) {
+        throw new TypeError("A validated settings layer unexpectedly failed its encoded schema.");
+    }
+    const candidate = options.update(currentForUpdate);
+    let candidateJson;
+    try {
+        candidateJson = Value.Parse(JsonValueSchema, candidate);
+    }
+    catch {
+        return invalidUpdate("The settings updater must return a JSON object.", [
+            { path: "/", message: "Expected a JSON object" },
+        ]);
+    }
+    if (!isJsonObject(candidateJson)) {
+        return invalidUpdate("The settings updater must return a JSON object.", [
+            { path: "/", message: "Expected a JSON object" },
+        ]);
+    }
+    if ("$schema" in candidateJson) {
+        return invalidUpdate("The settings updater cannot modify $schema metadata.", [
+            { path: "/$schema", message: "$schema is reserved for editor metadata" },
+        ]);
+    }
+    if (!Value.Check(layerSchema, candidateJson)) {
+        return invalidUpdate("The settings update does not match the extension schema.", settingsValidationIssues(layerSchema, candidateJson));
+    }
+    const nextLayer = cloneJson(candidateJson);
+    const resolved = mergeSettings(validationBase, nextLayer);
+    if (!Value.Check(definition.schema, resolved)) {
+        return invalidUpdate("The settings update conflicts with the resolved configuration.", settingsValidationIssues(definition.schema, resolved));
+    }
+    try {
+        Value.Decode(Value.Clone(definition.schema), resolved);
+    }
+    catch {
+        return invalidUpdate("The settings update could not be decoded.", [
+            { path: "/", message: "The resolved settings codec rejected the update" },
+        ]);
+    }
+    if (isDeepStrictEqual(currentLayer.settings, nextLayer)) {
+        return { status: "unchanged", revision };
+    }
+    const targetPaths = options.scope === "global" ? options.paths.global : options.paths.project;
+    const schemaReference = currentLayer.schemaReference ??
+        (options.scope === "global" ? targetPaths.schemaReference : definition.schemaId);
+    const content = formatJson(createSettingsDocument(definition.id, nextLayer, schemaReference));
+    await persistently(() => writeTextAtomicallyAsync(targetPaths.configPath, content));
+    const nextRevision = options.scope === "global"
+        ? createSettingsRevision(content)
+        : createSettingsRevision(globalText, content);
+    return { status: "updated", revision: nextRevision };
+}
+export async function updateSettingsTransaction(definition, options) {
+    if (options.scope === "project" && !options.projectTrusted) {
+        return {
+            status: "blocked",
+            reason: "project-untrusted",
+            message: "Project settings can only be updated for a trusted project.",
+        };
+    }
+    const lockPaths = options.scope === "global"
+        ? [options.paths.global.configPath]
+        : [options.paths.global.configPath, options.paths.project.configPath].sort();
+    try {
+        return await withInterprocessLocks(lockPaths, () => runSettingsTransaction(definition, options));
+    }
+    catch (cause) {
+        if (cause instanceof SettingsPersistenceError) {
+            return {
+                status: "failed",
+                message: `The ${options.scope} settings transaction failed.`,
+            };
+        }
+        if (cause instanceof Error)
+            throw cause;
+        throw new Error("The settings transaction threw a non-Error value.", { cause });
+    }
+}
+//# sourceMappingURL=settings-transaction.js.map

package/node_modules/@zigai/pi-extension-settings/dist/settings-transaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings-transaction.js","sourceRoot":"","sources":["../src/settings-transaction.ts"],"names":[],"mappings":"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","sourcesContent":["import { mkdir } from \"node:fs/promises\";\nimport { dirname } from \"node:path\";\nimport { isDeepStrictEqual } from \"node:util\";\n\nimport lockfile from \"proper-lockfile\";\nimport type { TObject, TSchema } from \"typebox\";\n\nimport type { ExtensionSettingsDefinition, ExtensionSettingsLayer } from \"./definition.ts\";\nimport { readTextIfPresentAsync, writeTextAtomicallyAsync } from \"./file-system.ts\";\nimport {\n    cloneJson,\n    formatJson,\n    isJsonObject,\n    JsonValueSchema,\n    type JsonObject,\n} from \"./json-value.ts\";\nimport { Value } from \"./typebox-runtime.ts\";\nimport type { ExtensionSettingsPaths } from \"./paths.ts\";\nimport { createSettingsDocument, createSettingsFileSchema } from \"./schema-document.ts\";\nimport {\n    applySettingsLayer,\n    parseSettingsLayer,\n    settingsValidationIssues,\n    type SettingsDiagnostic,\n    type SettingsScope,\n    type SettingsValidationIssue,\n} from \"./settings-layer.ts\";\nimport { mergeSettings } from \"./settings-merge.ts\";\nimport { createSettingsRevision, type PiSettingsRevision } from \"./settings-revision.ts\";\n\nexport type PiSettingsUpdateScope = \"global\" | \"project\";\n\nexport type PiSettingsUpdateIssue = SettingsValidationIssue;\n\nexport type UpdatePiExtensionSettingsOptions<Schema extends TObject> = {\n    /** Settings layer to update. Project updates require a trusted project. */\n    readonly scope: PiSettingsUpdateScope;\n    /** Reject the update if the relevant sources no longer match this loader revision. */\n    readonly expectedRevision?: PiSettingsRevision;\n    /**\n     * Produce the next encoded settings layer from the latest valid layer.\n     *\n     * The callback is invoked once, synchronously, while the settings transaction is locked. It may\n     * return a copy or mutate and return the supplied clone. Throwing an `Error` aborts the\n     * transaction and rejects `updatePiExtensionSettings` with the same error.\n     */\n    readonly update: (current: ExtensionSettingsLayer<Schema>) => ExtensionSettingsLayer<Schema>;\n};\n\nexport type UpdatePiExtensionSettingsResult =\n    | {\n          readonly status: \"updated\" | \"unchanged\";\n          readonly revision: PiSettingsRevision;\n      }\n    | {\n          readonly status: \"conflict\";\n          readonly reason: \"schema-changed\" | \"settings-changed\";\n          readonly message: string;\n      }\n    | {\n          readonly status: \"blocked\";\n          readonly reason: \"project-untrusted\";\n          readonly message: string;\n      }\n    | {\n          readonly status: \"invalid-existing\";\n          readonly message: string;\n          readonly diagnostics: readonly SettingsDiagnostic[];\n      }\n    | {\n          readonly status: \"invalid-update\";\n          readonly message: string;\n          readonly issues: readonly PiSettingsUpdateIssue[];\n      }\n    | {\n          readonly status: \"failed\";\n          readonly message: string;\n      };\n\nexport type SettingsTransactionPaths = {\n    readonly global: ExtensionSettingsPaths;\n    readonly project: ExtensionSettingsPaths;\n};\n\nexport type SettingsTransactionOptions<Schema extends TObject> =\n    UpdatePiExtensionSettingsOptions<Schema> & {\n        readonly paths: SettingsTransactionPaths;\n        readonly projectTrusted: boolean;\n    };\n\ntype ExistingLayerResult =\n    | {\n          readonly status: \"valid\";\n          readonly settings: JsonObject;\n          readonly schemaReference: string | undefined;\n      }\n    | {\n          readonly status: \"invalid\";\n          readonly diagnostics: readonly SettingsDiagnostic[];\n      };\n\nclass SettingsPersistenceError extends Error {\n    constructor(cause: unknown) {\n        super(\"The settings transaction could not access persistent storage.\", { cause });\n    }\n}\n\nasync function persistently<Result>(operation: () => Promise<Result>): Promise<Result> {\n    try {\n        return await operation();\n    } catch (cause: unknown) {\n        throw new SettingsPersistenceError(cause);\n    }\n}\n\nfunction typedSettingsLayer<Schema extends TObject>(\n    schema: TSchema,\n    value: JsonObject,\n): value is JsonObject & ExtensionSettingsLayer<Schema> {\n    return isJsonObject(value) && !(\"$schema\" in value) && Value.Check(schema, value);\n}\n\nfunction parseExistingLayer(\n    path: string,\n    scope: SettingsScope,\n    text: string | undefined,\n    layerSchema: TSchema,\n): ExistingLayerResult {\n    if (text === undefined) {\n        return {\n            status: \"valid\",\n            settings: {},\n            schemaReference: undefined,\n        };\n    }\n\n    const parsedLayer = parseSettingsLayer(path, scope, text, layerSchema);\n    if (parsedLayer.settings === undefined) {\n        return { status: \"invalid\", diagnostics: parsedLayer.diagnostics };\n    }\n    return {\n        status: \"valid\",\n        settings: parsedLayer.settings,\n        schemaReference: parsedLayer.schemaReference,\n    };\n}\n\nfunction invalidExisting(\n    diagnostics: readonly SettingsDiagnostic[],\n): UpdatePiExtensionSettingsResult {\n    return {\n        status: \"invalid-existing\",\n        message: diagnostics[0]?.message ?? \"The existing settings are invalid.\",\n        diagnostics,\n    };\n}\n\nfunction invalidUpdate(\n    message: string,\n    issues: readonly PiSettingsUpdateIssue[],\n): UpdatePiExtensionSettingsResult {\n    return { status: \"invalid-update\", message, issues };\n}\n\nasync function withInterprocessLocks<Result>(\n    paths: readonly string[],\n    operation: () => Promise<Result>,\n    index = 0,\n): Promise<Result> {\n    const path = paths[index];\n    if (path === undefined) return operation();\n\n    await persistently(() => mkdir(dirname(path), { recursive: true }));\n    const release = await persistently(() =>\n        lockfile.lock(path, {\n            realpath: false,\n            retries: {\n                retries: 20,\n                factor: 1.25,\n                minTimeout: 10,\n                maxTimeout: 100,\n                randomize: true,\n            },\n        }),\n    );\n    try {\n        return await withInterprocessLocks(paths, operation, index + 1);\n    } finally {\n        await persistently(release);\n    }\n}\n\nasync function runSettingsTransaction<Schema extends TObject>(\n    definition: ExtensionSettingsDefinition<Schema>,\n    options: SettingsTransactionOptions<Schema>,\n): Promise<UpdatePiExtensionSettingsResult> {\n    const layerSchema = createSettingsFileSchema(definition);\n    const expectedSchema = formatJson(layerSchema);\n    const installedSchema = await persistently(() =>\n        readTextIfPresentAsync(options.paths.global.schemaPath),\n    );\n    if (installedSchema !== expectedSchema) {\n        return {\n            status: \"conflict\",\n            reason: \"schema-changed\",\n            message: \"The installed settings schema changed; reload the extension before saving.\",\n        };\n    }\n\n    const globalText = await persistently(() =>\n        readTextIfPresentAsync(options.paths.global.configPath),\n    );\n    const projectText =\n        options.scope === \"project\"\n            ? await persistently(() => readTextIfPresentAsync(options.paths.project.configPath))\n            : undefined;\n    const revision =\n        options.scope === \"global\"\n            ? createSettingsRevision(globalText)\n            : createSettingsRevision(globalText, projectText);\n    if (options.expectedRevision !== undefined && options.expectedRevision !== revision) {\n        return {\n            status: \"conflict\",\n            reason: \"settings-changed\",\n            message: \"The settings changed after they were loaded; reload before saving.\",\n        };\n    }\n\n    const globalResult = parseExistingLayer(\n        options.paths.global.configPath,\n        \"global\",\n        globalText,\n        layerSchema,\n    );\n    if (globalResult.status === \"invalid\") return invalidExisting(globalResult.diagnostics);\n\n    const globalApplied = applySettingsLayer(\n        definition.schema,\n        definition.defaultSettings,\n        globalResult,\n        options.paths.global.configPath,\n        \"global\",\n    );\n    if (globalApplied.diagnostic !== undefined) {\n        return invalidExisting([globalApplied.diagnostic]);\n    }\n\n    let currentLayer = globalResult;\n    let validationBase = definition.defaultSettings;\n    if (options.scope === \"project\") {\n        const projectResult = parseExistingLayer(\n            options.paths.project.configPath,\n            \"project\",\n            projectText,\n            layerSchema,\n        );\n        if (projectResult.status === \"invalid\") return invalidExisting(projectResult.diagnostics);\n\n        const projectApplied = applySettingsLayer(\n            definition.schema,\n            globalApplied.settings,\n            projectResult,\n            options.paths.project.configPath,\n            \"project\",\n        );\n        if (projectApplied.diagnostic !== undefined) {\n            return invalidExisting([projectApplied.diagnostic]);\n        }\n        currentLayer = projectResult;\n        validationBase = globalApplied.settings;\n    }\n\n    const currentForUpdate = cloneJson(currentLayer.settings);\n    if (!typedSettingsLayer<Schema>(layerSchema, currentForUpdate)) {\n        throw new TypeError(\"A validated settings layer unexpectedly failed its encoded schema.\");\n    }\n\n    const candidate: unknown = options.update(currentForUpdate);\n    let candidateJson;\n    try {\n        candidateJson = Value.Parse(JsonValueSchema, candidate);\n    } catch {\n        return invalidUpdate(\"The settings updater must return a JSON object.\", [\n            { path: \"/\", message: \"Expected a JSON object\" },\n        ]);\n    }\n    if (!isJsonObject(candidateJson)) {\n        return invalidUpdate(\"The settings updater must return a JSON object.\", [\n            { path: \"/\", message: \"Expected a JSON object\" },\n        ]);\n    }\n    if (\"$schema\" in candidateJson) {\n        return invalidUpdate(\"The settings updater cannot modify $schema metadata.\", [\n            { path: \"/$schema\", message: \"$schema is reserved for editor metadata\" },\n        ]);\n    }\n    if (!Value.Check(layerSchema, candidateJson)) {\n        return invalidUpdate(\n            \"The settings update does not match the extension schema.\",\n            settingsValidationIssues(layerSchema, candidateJson),\n        );\n    }\n\n    const nextLayer = cloneJson(candidateJson);\n    const resolved = mergeSettings(validationBase, nextLayer);\n    if (!Value.Check(definition.schema, resolved)) {\n        return invalidUpdate(\n            \"The settings update conflicts with the resolved configuration.\",\n            settingsValidationIssues(definition.schema, resolved),\n        );\n    }\n    try {\n        Value.Decode(Value.Clone(definition.schema), resolved);\n    } catch {\n        return invalidUpdate(\"The settings update could not be decoded.\", [\n            { path: \"/\", message: \"The resolved settings codec rejected the update\" },\n        ]);\n    }\n\n    if (isDeepStrictEqual(currentLayer.settings, nextLayer)) {\n        return { status: \"unchanged\", revision };\n    }\n\n    const targetPaths = options.scope === \"global\" ? options.paths.global : options.paths.project;\n    const schemaReference =\n        currentLayer.schemaReference ??\n        (options.scope === \"global\" ? targetPaths.schemaReference : definition.schemaId);\n    const content = formatJson(createSettingsDocument(definition.id, nextLayer, schemaReference));\n    await persistently(() => writeTextAtomicallyAsync(targetPaths.configPath, content));\n    const nextRevision =\n        options.scope === \"global\"\n            ? createSettingsRevision(content)\n            : createSettingsRevision(globalText, content);\n    return { status: \"updated\", revision: nextRevision };\n}\n\nexport async function updateSettingsTransaction<Schema extends TObject>(\n    definition: ExtensionSettingsDefinition<Schema>,\n    options: SettingsTransactionOptions<Schema>,\n): Promise<UpdatePiExtensionSettingsResult> {\n    if (options.scope === \"project\" && !options.projectTrusted) {\n        return {\n            status: \"blocked\",\n            reason: \"project-untrusted\",\n            message: \"Project settings can only be updated for a trusted project.\",\n        };\n    }\n\n    const lockPaths =\n        options.scope === \"global\"\n            ? [options.paths.global.configPath]\n            : [options.paths.global.configPath, options.paths.project.configPath].sort();\n    try {\n        return await withInterprocessLocks(lockPaths, () =>\n            runSettingsTransaction(definition, options),\n        );\n    } catch (cause: unknown) {\n        if (cause instanceof SettingsPersistenceError) {\n            return {\n                status: \"failed\",\n                message: `The ${options.scope} settings transaction failed.`,\n            };\n        }\n        if (cause instanceof Error) throw cause;\n        throw new Error(\"The settings transaction threw a non-Error value.\", { cause });\n    }\n}\n"]}

package/node_modules/@zigai/pi-extension-settings/dist/typebox-runtime.d.ts

@@ -0,0 +1,5 @@
+export declare const Typebox: typeof import("typebox");
+export declare const IsSchema: typeof import("typebox").IsSchema;
+export declare const Type: typeof import("typebox").Type;
+export declare const Value: typeof import("typebox/value").Value;
+//# sourceMappingURL=typebox-runtime.d.ts.map

package/node_modules/@zigai/pi-extension-settings/dist/typebox-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typebox-runtime.d.ts","sourceRoot":"","sources":["../src/typebox-runtime.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,OAAO,EAAE,cAAc,SAAS,CAAW,CAAC;AACzD,eAAO,MAAM,QAAQ,EAAE,cAAc,SAAS,EAAE,QAA2B,CAAC;AAC5E,eAAO,MAAM,IAAI,EAAE,cAAc,SAAS,EAAE,IAAmB,CAAC;AAChE,eAAO,MAAM,KAAK,EAAE,cAAc,eAAe,EAAE,KAAoB,CAAC"}

package/node_modules/@zigai/pi-extension-settings/dist/typebox-runtime.js

@@ -0,0 +1,9 @@
+import * as typebox from "typebox";
+import { Value as typeboxValue } from "typebox/value";
+// Pi-facing runtime bundles retain these as externals in generated .ts entries, so Pi's loader
+// supplies the host-owned TypeBox modules. Authoring/CLI code resolves the package peer normally.
+export const Typebox = typebox;
+export const IsSchema = typebox.IsSchema;
+export const Type = typebox.Type;
+export const Value = typeboxValue;
+//# sourceMappingURL=typebox-runtime.js.map

package/node_modules/@zigai/pi-extension-settings/dist/typebox-runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"typebox-runtime.js","sourceRoot":"","sources":["../src/typebox-runtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,OAAO,MAAM,SAAS,CAAC;AACnC,OAAO,EAAE,KAAK,IAAI,YAAY,EAAE,MAAM,eAAe,CAAC;AAEtD,+FAA+F;AAC/F,kGAAkG;AAClG,MAAM,CAAC,MAAM,OAAO,GAA6B,OAAO,CAAC;AACzD,MAAM,CAAC,MAAM,QAAQ,GAAsC,OAAO,CAAC,QAAQ,CAAC;AAC5E,MAAM,CAAC,MAAM,IAAI,GAAkC,OAAO,CAAC,IAAI,CAAC;AAChE,MAAM,CAAC,MAAM,KAAK,GAAyC,YAAY,CAAC","sourcesContent":["import * as typebox from \"typebox\";\nimport { Value as typeboxValue } from \"typebox/value\";\n\n// Pi-facing runtime bundles retain these as externals in generated .ts entries, so Pi's loader\n// supplies the host-owned TypeBox modules. Authoring/CLI code resolves the package peer normally.\nexport const Typebox: typeof import(\"typebox\") = typebox;\nexport const IsSchema: typeof import(\"typebox\").IsSchema = typebox.IsSchema;\nexport const Type: typeof import(\"typebox\").Type = typebox.Type;\nexport const Value: typeof import(\"typebox/value\").Value = typeboxValue;\n"]}

package/node_modules/@zigai/pi-extension-settings/docs/generation.md

@@ -0,0 +1,71 @@
+# Generated artifacts and commands
+
+The CLI turns each package's `piExtensionSettings` manifest into checked-in artifacts. It supports a standalone package and npm workspaces.
+
+## Manifest
+
+```json
+{
+  "piExtensionSettings": {
+    "definition": "./src/settings-input.ts",
+    "prevalidation": "./src/settings.prevalidated.ts"
+  }
+}
+```
+
+| Field           | Required | Default                   | Purpose                                                                             |
+| --------------- | -------- | ------------------------- | ----------------------------------------------------------------------------------- |
+| `definition`    | yes      | —                         | TypeScript module whose default export is a settings definition or definition input |
+| `prevalidation` | no       | —                         | Generated runtime artifact path                                                     |
+| `schema`        | no       | `config.schema.json`      | Generated JSON Schema path                                                          |
+| `readme`        | no       | `README.md`               | README whose marked configuration section is generated                              |
+| `globalPath`    | no       | Pi's standard global path | Display path used in generated README documentation                                 |
+
+Every configured path must be relative and remain inside its package. The README must already exist. If the package uses a `files` allowlist, its published artifact must include the definition and prevalidation modules named by the manifest.
+
+Definitions may include `exampleSettings` when structured or interacting options benefit from a realistic non-default example. Generation validates the example and includes it in the generated README section.
+
+## Generate artifacts
+
+```sh
+pi-extension-settings generate
+```
+
+`generate` imports and validates each discovered definition, then updates the JSON Schema, optional prevalidation artifact, and marked README section. Invalid inputs fail before writes begin, and current files remain unchanged.
+
+The command mutates checked-in files. Projects can run it explicitly or through their preferred authoring automation.
+
+## Verify artifacts
+
+```sh
+pi-extension-settings check
+```
+
+`check` performs the same discovery and validation without modifying files. It fails for invalid inputs and missing or stale artifacts, making it suitable for pre-commit, CI, verification, and release gates.
+
+For prevalidated definitions, `check` also compares codec function text and non-enumerable schema metadata. Runtime hydration checks the JSON-visible contract only: Pi and bundlers can rewrite equivalent codec functions. Run `generate` and `check` against the authoring source before packaging.
+
+## Package scripts
+
+Short package scripts keep automation independent of the installed CLI path:
+
+```json
+{
+  "scripts": {
+    "config:generate": "pi-extension-settings generate",
+    "config:check": "pi-extension-settings check"
+  }
+}
+```
+
+These names are conventions, not requirements. Include `config:check` in the package's canonical verification command so stale generated files cannot be released.
+
+## Roots and workspaces
+
+Commands use the current directory by default. Pass `--root` for another package or npm workspace root:
+
+```sh
+pi-extension-settings check --root ./path/to/repository
+```
+
+At a workspace root, the CLI reads the root package and packages matched by its npm `workspaces` patterns. Only packages with a `piExtensionSettings` manifest participate.

package/node_modules/@zigai/pi-extension-settings/docs/manual-setup.md

@@ -0,0 +1,98 @@
+# Add settings to an existing Pi extension
+
+This guide adds typed settings to an existing TypeScript Pi extension. For a new extension, [Pi Extension Template](https://github.com/zigai/pi-extension-template) generates this structure for you.
+
+## 1. Install the package
+
+```sh
+npm install @zigai/pi-extension-settings
+```
+
+## 2. Define the settings
+
+Keep authoring-only schema code in `src/settings-input.ts`. The generator imports this file, so it must not import Pi runtime code or the generated prevalidation artifact.
+
+```ts
+import type { ExtensionSettingsDefinitionInput } from "@zigai/pi-extension-settings";
+import { Type } from "typebox";
+
+export const settingsSchema = Type.Object(
+  {
+    enabled: Type.Boolean({
+      default: true,
+      description: "Enable the extension's behavior.",
+    }),
+    excludedTools: Type.Array(Type.String(), {
+      default: [],
+      description: "Tool names the extension should ignore.",
+    }),
+  },
+  { additionalProperties: false },
+);
+
+const settingsInput = {
+  id: "pi-example",
+  title: "Pi Example",
+  description: "Settings for Pi Example.",
+  schemaId: "https://raw.githubusercontent.com/zigai/pi-example/main/config.schema.json",
+  schema: settingsSchema,
+} as const satisfies ExtensionSettingsDefinitionInput<typeof settingsSchema>;
+
+export default settingsInput;
+```
+
+## 3. Configure generation
+
+Add the settings manifest and commands to `package.json`:
+
+```json
+{
+  "piExtensionSettings": {
+    "definition": "./src/settings-input.ts",
+    "prevalidation": "./src/settings.prevalidated.ts"
+  },
+  "scripts": {
+    "config:generate": "pi-extension-settings generate",
+    "config:check": "pi-extension-settings check"
+  }
+}
+```
+
+The generated schema and README paths default to `config.schema.json` and `README.md`. Set `schema` or `readme` in the manifest only when those defaults do not fit the package.
+
+If `package.json` uses a `files` allowlist, publish both manifest targets. Including `src` is sufficient; a bundled package can include `src/settings-input.ts` and `src/settings.prevalidated.ts` explicitly.
+
+Generate the initial artifacts:
+
+```sh
+npm run config:generate
+```
+
+Commit the generated `config.schema.json`, `src/settings.prevalidated.ts`, and README settings section. See [Generated artifacts and commands](generation.md) for command behavior, workspace discovery, manifest options, and automation guidance.
+
+## 4. Create the runtime loader
+
+Keep the runtime definition and loader in `src/settings.ts`:
+
+```ts
+import { loadPiExtensionSettings, type PiSettingsContext } from "@zigai/pi-extension-settings/pi";
+import { definePrevalidatedExtensionSettings } from "@zigai/pi-extension-settings/runtime";
+import type { StaticDecode } from "typebox";
+
+import artifact from "./settings.prevalidated.ts";
+import settingsInput, { settingsSchema } from "./settings-input.ts";
+
+export type ExtensionSettings = StaticDecode<typeof settingsSchema>;
+
+export const settingsDefinition = definePrevalidatedExtensionSettings(settingsInput, artifact);
+
+export function loadExampleSettings(ctx: PiSettingsContext) {
+  return loadPiExtensionSettings(settingsDefinition, ctx, {
+    bundledSchema: { kind: "url", url: new URL("../config.schema.json", import.meta.url) },
+  });
+}
+```
+
+Use `StaticDecode`, not `Static`, for values after TypeBox codecs run.
+
+Do not load settings during module import or the extension factory. Resolve them once per session at the first lifecycle event that needs them. See [Runtime loading and updates](runtime.md) for lifecycle guidance, merge behavior, diagnostics, and transactional writes.

package/node_modules/@zigai/pi-extension-settings/docs/runtime.md

@@ -0,0 +1,100 @@
+# Runtime loading and updates
+
+Pi Extension Settings separates authoring-time schema work from the code loaded by Pi.
+
+| Import                                 | Use it for                                                        |
+| -------------------------------------- | ----------------------------------------------------------------- |
+| `@zigai/pi-extension-settings`         | Defining and generating settings in Node.js authoring tools       |
+| `@zigai/pi-extension-settings/runtime` | Hydrating the checked-in prevalidation artifact in extension code |
+| `@zigai/pi-extension-settings/pi`      | Loading and updating settings through Pi paths and project trust  |
+
+## Load settings
+
+```ts
+import { loadPiExtensionSettings } from "@zigai/pi-extension-settings/pi";
+import settingsDefinition from "./settings.ts";
+
+const loaded = loadPiExtensionSettings(settingsDefinition, ctx, {
+  bundledSchema: {
+    kind: "url",
+    url: new URL("../config.schema.json", import.meta.url),
+  },
+});
+```
+
+Resolution applies layers in this order:
+
+1. Schema defaults.
+2. Global settings.
+3. Trusted-project settings.
+
+Objects merge recursively. Arrays and scalar values replace earlier values. Invalid layers are ignored and reported through `loaded.diagnostics` without exposing their values.
+
+Global settings are stored under Pi's agent directory at `extension-settings/<id>.json`. Trusted-project overrides use `<project>/<Pi config directory>/extension-settings/<id>.json`. `getPiGlobalSettingsPath()` and `getPiProjectSettingsPath()` return the resolved paths.
+
+Loading installs or refreshes the generated editor schema and creates a missing global settings file. It never overwrites an existing settings file and never creates a project settings file.
+
+### Choose the activation boundary
+
+Keep module import and the extension factory free of settings I/O. Treat `session_start` as the reset boundary and load settings once in the first callback that needs them. If the feature genuinely begins during `session_start`, that handler is the correct activation boundary.
+
+Cache the load result inside the extension factory. A cached result means loading is complete even when `enabled` is false; no separate activation flag is needed. Call the same getter from each tool execution, command, shortcut, or event handler that needs settings. Keep additional extension-specific validation with that getter and cache rejected results too.
+
+```ts
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { loadExampleSettings, type ExtensionSettings } from "./settings.ts";
+
+export default function extension(pi: ExtensionAPI): void {
+  let loaded: ReturnType<typeof loadExampleSettings> | undefined;
+
+  function getSettings(ctx: ExtensionContext): ExtensionSettings | undefined {
+    if (loaded === undefined) {
+      loaded = loadExampleSettings(ctx);
+      if (ctx.hasUI) {
+        for (const diagnostic of loaded.diagnostics) {
+          ctx.ui.notify(diagnostic.message, diagnostic.severity);
+        }
+      }
+    }
+    return loaded.settings.enabled ? loaded.settings : undefined;
+  }
+
+  const reset = () => {
+    loaded = undefined;
+  };
+  pi.on("session_start", reset);
+  pi.on("session_shutdown", reset);
+
+  pi.on("before_agent_start", (_event, ctx) => {
+    const settings = getSettings(ctx);
+    if (settings === undefined) return;
+
+    // Run enabled behavior that needs settings.
+  });
+}
+```
+
+Renderers receive `ToolRenderContext`, not `ExtensionContext`. Keep rendering free of settings I/O and notifications; use presentation data captured during execution or already-owned session state. Renderers must also handle history rendered before settings activation and still return a component.
+
+This moves synchronous settings work from Pi startup to first feature use; it does not eliminate that cost. Pi-level package configuration is the zero-load switch when an extension should not be imported or registered at all. Add cancellation, stale-result rejection, and disposal when the extension acquires asynchronous work or resources that need them.
+
+## Update settings safely
+
+Use `updatePiExtensionSettings()` instead of writing settings files directly. Load first so the generated editor schema is installed and verified.
+
+```ts
+import { updatePiExtensionSettings } from "@zigai/pi-extension-settings/pi";
+
+const result = await updatePiExtensionSettings(settingsDefinition, ctx, {
+  scope: "global",
+  update: (current) => ({ ...current, enabled: false }),
+});
+
+if (result.status !== "updated" && result.status !== "unchanged") {
+  ctx.ui.notify(result.message, "error");
+}
+```
+
+The synchronous callback receives the latest encoded layer and runs once while the settings file is locked. The package validates the returned layer by itself and after resolution, then publishes it atomically. Invalid existing files and invalid updates remain untouched. Project updates require a trusted project and may create its missing settings file.
+
+For an editor based on a previously loaded snapshot, pass `globalRevision` or `projectRevision` as `expectedRevision`. A stale revision returns `conflict`. Omit it for semantic updates that should apply to the latest valid layer.

package/node_modules/@zigai/pi-extension-settings/docs/ui-controls.md

@@ -0,0 +1,31 @@
+# Optional UI controls
+
+The optional `x-control` TypeBox annotation tells compatible settings editors how to present a property. It does not change validation, defaults, or runtime loading.
+
+[Pi Settings UI](https://github.com/zigai/pi-settings-ui) supports these values:
+
+| `x-control`   | Compatible schema           | Presentation                                                            |
+| ------------- | --------------------------- | ----------------------------------------------------------------------- |
+| `text`        | string                      | Single-line input                                                       |
+| `textarea`    | string                      | Multiline editor                                                        |
+| `switch`      | boolean                     | Toggle                                                                  |
+| `segmented`   | primitive choices           | Compact choice control                                                  |
+| `select`      | primitive choices           | Searchable picker                                                       |
+| `slider`      | number or integer           | Range control using schema bounds and `multipleOf`                      |
+| `numeric`     | number or integer           | Numeric input                                                           |
+| `color`       | string                      | Text input with a hexadecimal color preview                             |
+| `path`        | string                      | Text input with Tab completion                                          |
+| `combobox`    | string or string-only union | Suggestions from `examples` or union branches, plus custom valid values |
+| `json-editor` | any property schema         | Validated JSON editor                                                   |
+
+Pass the annotation as a quoted schema option:
+
+```ts
+const enabled = Type.Boolean({
+  default: true,
+  description: "Enable the extension's behavior.",
+  "x-control": "switch",
+});
+```
+
+Choose a control only when it communicates the setting more clearly than the editor's schema-derived default.