@peers-app/peers-sdk 0.26.5 → 0.27.0

package/dist/package-build/cli.js

@@ -0,0 +1,218 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.main = main;
+const node_fs_1 = require("node:fs");
+const path = require("node:path");
+const build_package_1 = require("./build-package");
+const contract_add_1 = require("./contract-add");
+const freeze_contracts_1 = require("./freeze-contracts");
+const USAGE = `Usage: peers-package <command> [options]
+
+Commands:
+  manifest              Write dist/manifest.json from the package's declarations (src/package.ts).
+  build                 Write the manifest and dist/package.bundle.js, the artifact the Runtime
+                        installs.
+  contract add <source> Write src/contracts/<name>.v<version>.ts, a declaration of a contract this
+                        package implements or calls, generated from <source>: a declaration module
+                        and its export (path/to/file.ts#Name), a provider's manifest.json or
+                        package.bundle.js, or the JSON getContractDefinition returned.
+  contract freeze       Before releasing a version as stable: record the contract versions it
+                        provides in frozen-contracts.json, whose shapes can't change again. A
+                        build fails if it changes one.
+
+Options:
+  --watch            Rebuild on every change (build only).
+  --root <dir>       Package root. Defaults to the current directory.
+  --entry <file>     Declaration module. Defaults to src/package.ts.
+  --out-dir <dir>    Output directory. Defaults to dist (src/contracts for contract add).
+  --contract <id@v>  The contract to read, when a manifest provides several (contract add).
+  --name <Name>      The declaration's export name (contract add).
+  --check            Write nothing; fail if the declaration is missing or out of date
+                     (contract add), or if a frozen contract changed (contract freeze).
+  --bundle <file>    Read the contracts from a built bundle instead of src/package.ts: an
+                     isolated package.bundle.js, or a host-backed package's CommonJS bundle
+                     (contract freeze).
+`;
+function readOptions(args) {
+    const options = { watch: false };
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        const value = () => {
+            const next = args[index + 1];
+            if (next === undefined || next.startsWith("--")) {
+                throw new Error(`${arg} needs a value`);
+            }
+            index += 1;
+            return next;
+        };
+        if (arg === "--watch")
+            options.watch = true;
+        else if (arg === "--root")
+            options.root = value();
+        else if (arg === "--entry")
+            options.entry = value();
+        else if (arg === "--out-dir")
+            options.outDir = value();
+        else
+            throw new Error(`Unknown option ${arg}`);
+    }
+    return options;
+}
+function summarize(result) {
+    const { manifest } = result;
+    const tools = manifest.provides.reduce((count, contract) => count + contract.tools.length, 0);
+    return `${manifest.provides.length} contract(s), ${tools} tool(s), ${manifest.tables?.length ?? 0} table(s)`;
+}
+function relative(file) {
+    return path.relative(process.cwd(), file) || file;
+}
+/**
+ * Run the `peers-package` command.
+ *
+ * @param argv - Arguments after the command name, such as `["build", "--watch"]`.
+ * @returns The exit code, or never resolves while watching.
+ */
+async function main(argv) {
+    const [command, ...rest] = argv;
+    if (command === "contract") {
+        return contractCommand(rest);
+    }
+    if (command !== "manifest" && command !== "build") {
+        process.stdout.write(USAGE);
+        return command === undefined || command === "--help" ? 0 : 1;
+    }
+    const { watch, ...options } = readOptions(rest);
+    if (command === "manifest") {
+        if (watch) {
+            throw new Error("--watch applies to build");
+        }
+        const result = await (0, build_package_1.generatePackageManifest)(options);
+        console.log(`Manifest: ${summarize(result)} -> ${relative(result.manifestPath)}`);
+        return 0;
+    }
+    if (watch) {
+        await (0, build_package_1.watchPackage)(options, (result) => {
+            if (result instanceof Error) {
+                console.error(`Build failed: ${result.message}`);
+                return;
+            }
+            console.log(`Built ${relative(result.artifactPath)} (${summarize(result)}; provider ${Math.round(result.providerChars / 1024)} KB)`);
+        });
+        console.log("Watching for changes");
+        return new Promise(() => undefined);
+    }
+    const result = await (0, build_package_1.buildPackage)(options);
+    console.log(`Built ${relative(result.artifactPath)} (${summarize(result)}; provider ${Math.round(result.providerChars / 1024)} KB)`);
+    return 0;
+}
+/** `peers-package contract add <source> [options]` or `peers-package contract freeze [options]`. */
+async function contractCommand(args) {
+    const [subcommand, source, ...rest] = args;
+    if (subcommand === "freeze")
+        return freezeCommand(args.slice(1));
+    if (subcommand !== "add" || source === undefined || source.startsWith("--")) {
+        process.stdout.write(USAGE);
+        return 1;
+    }
+    const options = { source };
+    for (let index = 0; index < rest.length; index += 1) {
+        const arg = rest[index];
+        const value = () => {
+            const next = rest[index + 1];
+            if (next === undefined || next.startsWith("--")) {
+                throw new Error(`${arg} needs a value`);
+            }
+            index += 1;
+            return next;
+        };
+        if (arg === "--check")
+            options.check = true;
+        else if (arg === "--root")
+            options.root = value();
+        else if (arg === "--out-dir")
+            options.outDir = value();
+        else if (arg === "--contract")
+            options.contract = value();
+        else if (arg === "--name")
+            options.name = value();
+        else
+            throw new Error(`Unknown option ${arg}`);
+    }
+    const result = await (0, contract_add_1.addContract)(options);
+    const file = relative(result.path);
+    if (options.check) {
+        if (!result.changed)
+            return 0;
+        const regenerate = ["peers-package", "contract", "add", source];
+        for (const [flag, value] of [
+            ["--root", options.root],
+            ["--out-dir", options.outDir],
+            ["--contract", options.contract],
+            ["--name", options.name],
+        ]) {
+            if (value !== undefined)
+                regenerate.push(flag, value);
+        }
+        const command = regenerate
+            .map((arg) => (/^[\w./:@#=-]+$/.test(arg) ? arg : `'${arg.replace(/'/g, "'\\''")}'`))
+            .join(" ");
+        console.error(`${file} is missing or out of date. Run: ${command}`);
+        return 1;
+    }
+    console.log(`${result.changed ? "Wrote" : "Unchanged:"} ${file} (${result.exportName})`);
+    return 0;
+}
+/** `peers-package contract freeze [--check] [--bundle <file>] [--root <dir>] [--entry <file>]`. */
+async function freezeCommand(args) {
+    const options = {};
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        const value = () => {
+            const next = args[index + 1];
+            if (next === undefined || next.startsWith("--")) {
+                throw new Error(`${arg} needs a value`);
+            }
+            index += 1;
+            return next;
+        };
+        if (arg === "--check")
+            options.check = true;
+        else if (arg === "--bundle")
+            options.bundle = value();
+        else if (arg === "--root")
+            options.root = value();
+        else if (arg === "--entry")
+            options.entry = value();
+        else
+            throw new Error(`Unknown option ${arg}`);
+    }
+    const result = await (0, freeze_contracts_1.freezePackageContracts)(options);
+    const file = relative(result.path);
+    for (const contract of result.check.notProvided) {
+        console.log(`Note: ${contract.name} (${contract.contractId}@${contract.version}), frozen by ${contract.frozenBy}, is no longer provided.`);
+    }
+    if (result.check.changed.length > 0) {
+        console.error(`A frozen contract changed (${file}):`);
+        for (const { contract, changes } of result.check.changed) {
+            console.error(`  ${contract.name} (${contract.contractId}@${contract.version}), frozen by ${contract.frozenBy}: ${changes.join("; ")}`);
+        }
+        console.error("Declare a new version of the contract instead.");
+        return 1;
+    }
+    if (options.check) {
+        // A package without the file has frozen nothing yet: the check passes but guards nothing.
+        console.log((0, node_fs_1.existsSync)(result.path)
+            ? `Frozen contracts unchanged (${file}).`
+            : `No ${file}: nothing is frozen yet. Run \`peers-package contract freeze\` before a stable release.`);
+        return 0;
+    }
+    if (!result.written) {
+        console.log(`Nothing new to freeze (${file}).`);
+        return 0;
+    }
+    for (const contract of result.added) {
+        console.log(`Froze ${contract.name} (${contract.contractId}@${contract.version}) as of ${contract.frozenBy}.`);
+    }
+    console.log(`Wrote ${file}. Commit it with the release.`);
+    return 0;
+}

package/dist/package-build/contract-add.d.ts

@@ -0,0 +1,35 @@
+/** What {@link addContract} takes. */
+export interface IContractAddOptions {
+    /**
+     * Where the contract comes from: a declaration module and its export
+     * (`../voice-hub/src/contracts/voice-skill.ts#VoiceSkill`), a provider's `manifest.json` or
+     * `package.bundle.js`, or the JSON `getContractDefinition` returned.
+     */
+    source: string;
+    /** `contractId@version`, for a manifest that provides more than one contract. */
+    contract?: string;
+    /** Package root. Defaults to the current directory. */
+    root?: string;
+    /** Where the file goes, relative to the root. Defaults to `src/contracts`. */
+    outDir?: string;
+    /** The declaration's export name, instead of the one made from the contract's name. */
+    name?: string;
+    /** Write nothing; report whether the file is missing or out of date. */
+    check?: boolean;
+}
+/** What {@link addContract} did. */
+export interface IContractAddResult {
+    /** The declaration file's path. */
+    path: string;
+    /** Its export name. */
+    exportName: string;
+    /** The file was (or, with `check`, would be) written or changed. */
+    changed: boolean;
+}
+/**
+ * Write (or check) a generated declaration for a contract this package implements or calls:
+ * `src/contracts/<name>.v<version>.ts`, formatted with the package's Biome when it has one.
+ *
+ * @param options - The source, and where the file goes.
+ */
+export declare function addContract(options: IContractAddOptions): Promise<IContractAddResult>;

package/dist/package-build/contract-add.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addContract = addContract;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const promises_1 = require("node:fs/promises");
+const path = require("node:path");
+const declare_contract_1 = require("../define/declare-contract");
+const define_package_1 = require("../define/define-package");
+const manifest_1 = require("../define/manifest");
+const isolated_artifact_1 = require("../package-loader/isolated-artifact");
+const build_package_1 = require("./build-package");
+const contract_source_1 = require("./contract-source");
+/**
+ * Write (or check) a generated declaration for a contract this package implements or calls:
+ * `src/contracts/<name>.v<version>.ts`, formatted with the package's Biome when it has one.
+ *
+ * @param options - The source, and where the file goes.
+ */
+async function addContract(options) {
+    const root = path.resolve(options.root ?? process.cwd());
+    const contract = await readContractSource(root, options);
+    const generated = (0, contract_source_1.generateContractDeclaration)(contract, {
+        from: sourceLabel(root, options.source),
+        ...(options.name ? { exportName: options.name } : {}),
+    });
+    const target = path.join(path.resolve(root, options.outDir ?? "src/contracts"), generated.fileName);
+    const source = formatSource(root, target, generated.source);
+    const current = (0, node_fs_1.existsSync)(target) ? await (0, promises_1.readFile)(target, "utf8") : undefined;
+    const changed = current !== source;
+    if (changed && !options.check) {
+        await (0, promises_1.mkdir)(path.dirname(target), { recursive: true });
+        await (0, promises_1.writeFile)(target, source, "utf8");
+    }
+    return { path: target, exportName: generated.exportName, changed };
+}
+/** A source's file and, for a declaration module, its export name (`file.ts#Name`). */
+function splitSource(source) {
+    const hash = source.lastIndexOf("#");
+    return hash > 0
+        ? { file: source.slice(0, hash), exportName: source.slice(hash + 1) }
+        : { file: source };
+}
+/**
+ * The source as the file's header names it: relative to the package root, with `/`, so the
+ * generated file (and `--check`) doesn't depend on where the command ran or on local paths.
+ */
+function sourceLabel(root, source) {
+    const { file, exportName } = splitSource(source);
+    const relative = path.relative(root, path.resolve(file)).split(path.sep).join("/");
+    return exportName === undefined ? relative : `${relative}#${exportName}`;
+}
+async function readContractSource(root, options) {
+    const { file, exportName } = splitSource(options.source);
+    if (exportName !== undefined) {
+        const loaded = (await (0, build_package_1.loadPackageModule)(root, path.resolve(file)));
+        const value = loaded?.[exportName];
+        if ((0, declare_contract_1.isContractDeclaration)(value))
+            return (0, manifest_1.contractManifest)(value.declaration);
+        if ((0, define_package_1.isPackageContract)(value))
+            return (0, manifest_1.contractManifest)(value);
+        throw new Error(`${file} exports no declaration or contract named ${exportName}; pass <file>#<export>`);
+    }
+    const text = (await (0, promises_1.readFile)(path.resolve(options.source), "utf8")).trimStart();
+    if ((0, isolated_artifact_1.looksLikeIsolatedPackageArtifact)(text)) {
+        const artifact = (0, isolated_artifact_1.parseIsolatedPackageArtifact)(text);
+        return (0, contract_source_1.contractSourceFromManifest)(artifact.manifest, options.contract);
+    }
+    const json = JSON.parse(text);
+    if (Array.isArray(json.provides)) {
+        return (0, contract_source_1.contractSourceFromManifest)(json, options.contract);
+    }
+    if (json.definition) {
+        return (0, contract_source_1.contractSourceFromDefinition)(json);
+    }
+    if (typeof json.contractId === "string") {
+        throw new Error(`${options.source} is a contract definition without its tools' access levels; use getContractDefinition's result instead`);
+    }
+    throw new Error(`${options.source} isn't a manifest, a package artifact, or getContractDefinition's result`);
+}
+/** The source as the package's Biome formats it (imports sorted), or as generated without one. */
+function formatSource(root, target, source) {
+    const shim = path.join(root, "node_modules", ".bin", "biome");
+    if (!(0, node_fs_1.existsSync)(shim))
+        return source;
+    const args = ["check", "--write", `--stdin-file-path=${target}`];
+    // Run Biome's Node script when it's there: Windows can't spawn the .bin shell shim itself.
+    const entry = path.join(root, "node_modules", "@biomejs", "biome", "bin", "biome");
+    const [command, commandArgs] = (0, node_fs_1.existsSync)(entry)
+        ? [process.execPath, [entry, ...args]]
+        : [shim, args];
+    const result = (0, node_child_process_1.spawnSync)(command, commandArgs, { cwd: root, input: source, encoding: "utf8" });
+    if (result.status !== 0 || !result.stdout) {
+        throw new Error(`Biome couldn't format the generated declaration: ${result.error?.message || result.stderr || result.stdout}`);
+    }
+    return result.stdout;
+}

package/dist/package-build/contract-add.test.d.ts

@@ -0,0 +1 @@
+export {};