@epinova/opticli 0.0.0-stage → 0.27.0-preview

package/lib/opticli.js

@@ -0,0 +1,208 @@
+// A typed wrapper around the opticli CLI. Every call runs `opticli <command> --json`, parses the JSON envelope it prints
+// on stdout, and returns `data`, or throws an OptiCliError for `ok: false`. What opticli checks (the local database, drift,
+// property names, plans) stays in the CLI: this module only runs it.
+import { spawn } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+/** opticli answered `ok: false`, or didn't answer with JSON (`code` `internal`). */
+export class OptiCliError extends Error {
+    code;
+    hint;
+    details;
+    exitCode;
+    /** The opticli version that failed, when it says (0.27.0 and newer). */
+    version;
+    args;
+    constructor(error, exitCode, args, version) {
+        super(`opticli ${args[0] ?? ''}: ${error.code}: ${error.message}${error.hint ? `\nHint: ${error.hint}` : ''}`);
+        this.name = 'OptiCliError';
+        this.code = error.code;
+        this.hint = error.hint;
+        this.details = error.details;
+        this.exitCode = exitCode;
+        this.version = version;
+        this.args = args;
+    }
+}
+export class OptiCli {
+    command;
+    project;
+    cwd;
+    onWarnings;
+    constructor(options = {}) {
+        this.cwd = options.cwd;
+        this.command = options.command ?? resolveCommand(options.cwd ?? process.cwd());
+        this.project = options.project ?? (process.env.OPTICLI_PROJECT || undefined);
+        this.onWarnings = options.onWarnings;
+    }
+    /** Runs any opticli command with `--json` and returns its envelope; throws OptiCliError when `ok` is false. */
+    async run(args, options = {}) {
+        const full = [...args, '--json', ...(this.project ? ['--project', this.project] : [])];
+        const { stdout, stderr, exitCode } = await this.exec(full, options);
+        let envelope;
+        try {
+            envelope = JSON.parse(stdout);
+        }
+        catch {
+            const output = (stderr || stdout).trim().slice(0, 2000);
+            throw new OptiCliError({ code: 'internal', message: `no JSON on stdout (exit ${exitCode}): ${output}` }, exitCode, args);
+        }
+        if (!envelope.ok)
+            throw new OptiCliError(envelope.error, exitCode, args, envelope.meta?.version);
+        if (envelope.meta?.warnings?.length)
+            this.onWarnings?.(envelope.meta.warnings, args);
+        return envelope;
+    }
+    async data(args, options) {
+        return (await this.run(args, options)).data;
+    }
+    // serve
+    /** Starts the site with the site agent in the background (`serve`), or returns the one that runs. */
+    serve(options = {}) {
+        const timeout = options.timeoutSeconds ?? 180;
+        const args = ['serve', '--timeout', String(timeout)];
+        if (options.build)
+            args.push('--build');
+        if (options.port)
+            args.push('--port', String(options.port));
+        if (options.https)
+            args.push('--https');
+        // A build comes first, and may take minutes.
+        return this.run(args, { timeoutMs: (timeout + 600) * 1000 });
+    }
+    serveStatus() {
+        return this.data(['serve', '--status']);
+    }
+    serveStop() {
+        return this.data(['serve', '--stop']);
+    }
+    // reads
+    get(ref, options = {}) {
+        const args = ['get', ref];
+        if (options.lang)
+            args.push('--lang', options.lang);
+        if (options.version)
+            args.push('--version', options.version);
+        if (options.full)
+            args.push('--full');
+        return this.data(args);
+    }
+    /** Every language branch's path and absolute URL. Write results have `url` already. */
+    url(ref) {
+        return this.data(['url', ref]);
+    }
+    // writes
+    create(parent, type, name, properties = {}, options = {}) {
+        return this.data(['create', parent, '--type', type, '--name', name, ...values(properties), ...writeFlags(options)]);
+    }
+    /** Saves a draft of the change, unless `publish`. */
+    set(ref, properties, options = {}) {
+        const args = ['set', ref, ...values(properties), ...writeFlags(options)];
+        if (options.name)
+            args.push('--name', options.name);
+        if (options.from)
+            args.push('--from', options.from);
+        return this.data(args);
+    }
+    /** Publishes the latest version, or the version `ref` names (`123_456`). */
+    publish(ref, options = {}) {
+        const args = ['publish', ref];
+        if (options.includeDraft)
+            args.push('--include-draft');
+        if (options.dryRun)
+            args.push('--dry-run');
+        return this.data(args);
+    }
+    /** Moves content, with everything below it, to the recycle bin. */
+    delete(ref, options = {}) {
+        const args = ['delete', ref];
+        if (options.ignoreReferences)
+            args.push('--ignore-references');
+        if (options.dryRun)
+            args.push('--dry-run');
+        return this.data(args);
+    }
+    /**
+     * Runs a plan, sent on stdin. Its files (`upload`, `"@file"` values) are relative to `baseDir` and must be inside it.
+     * With the plan's `guidNamespace` and `updateExisting`, running it again only changes what differs.
+     */
+    apply(plan, options = {}) {
+        const args = ['apply', '-'];
+        if (options.updateExisting)
+            args.push('--update-existing');
+        if (options.publish)
+            args.push('--publish');
+        if (options.dryRun)
+            args.push('--dry-run');
+        return this.data(args, { input: JSON.stringify(plan), cwd: options.baseDir, timeoutMs: 600_000 });
+    }
+    exec(args, options) {
+        const [program, ...prefix] = this.command;
+        return new Promise((resolvePromise, reject) => {
+            const child = spawn(program, [...prefix, ...args], {
+                cwd: options.cwd ?? this.cwd,
+                stdio: ['pipe', 'pipe', 'pipe'],
+                timeout: options.timeoutMs ?? 120_000,
+            });
+            let stdout = '';
+            let stderr = '';
+            child.stdout.setEncoding('utf8').on('data', (chunk) => (stdout += chunk));
+            child.stderr.setEncoding('utf8').on('data', (chunk) => (stderr += chunk));
+            child.on('error', (error) => reject(error.code === 'ENOENT'
+                ? new Error(`Couldn't run ${this.command.join(' ')}: install opticli (dotnet tool install -g OptiCli), or set OPTICLI to it.`, { cause: error })
+                : error));
+            child.on('close', (exitCode) => resolvePromise({ stdout, stderr, exitCode }));
+            child.stdin.on('error', () => { }); // a CLI that exits before reading stdin
+            child.stdin.end(options.input ?? '');
+        });
+    }
+}
+/** The command that runs opticli from `cwd`: see {@link OptiCliOptions.command}. */
+export function resolveCommand(cwd, env = process.env) {
+    const bin = env.OPTICLI;
+    if (bin)
+        return bin.endsWith('.dll') ? ['dotnet', bin] : [bin];
+    return findToolManifest(cwd) ? ['dotnet', 'tool', 'run', 'opticli'] : ['opticli'];
+}
+/** The nearest local tool manifest above `cwd` that has opticli, as `dotnet tool run` finds it. */
+export function findToolManifest(cwd) {
+    for (let dir = resolve(cwd);; dir = dirname(dir)) {
+        for (const file of [join(dir, '.config', 'dotnet-tools.json'), join(dir, 'dotnet-tools.json')]) {
+            if (!existsSync(file))
+                continue;
+            try {
+                const tools = JSON.parse(readFileSync(file, 'utf8')).tools ?? {};
+                if (Object.values(tools).some((tool) => tool.commands?.includes('opticli')))
+                    return file;
+            }
+            catch {
+                // Not JSON: dotnet would fail on it too. Keep looking above.
+            }
+        }
+        if (dirname(dir) === dir)
+            return undefined;
+    }
+}
+/** Compares `major.minor.patch` versions, ignoring a prerelease suffix: negative, zero or positive. */
+export function compareVersions(a, b) {
+    const parts = (v) => v.split(/[-+]/)[0].split('.').map((n) => Number.parseInt(n, 10) || 0);
+    const [x, y] = [parts(a), parts(b)];
+    for (let i = 0; i < 3; i++) {
+        if ((x[i] ?? 0) !== (y[i] ?? 0))
+            return (x[i] ?? 0) - (y[i] ?? 0);
+    }
+    return 0;
+}
+function values(properties) {
+    return Object.keys(properties).length ? ['--values', JSON.stringify(properties)] : [];
+}
+function writeFlags(options) {
+    const flags = [];
+    if (options.publish)
+        flags.push('--publish');
+    if (options.dryRun)
+        flags.push('--dry-run');
+    if (options.lang)
+        flags.push('--lang', options.lang);
+    return flags;
+}

package/lib/playwright/fixtures.d.ts

@@ -0,0 +1,58 @@
+import { OptiCli, type WriteOptions } from '../opticli.ts';
+import type { ApplyResult, ContentRef, Plan, PlanIds, Properties, WriteResult } from '../types.ts';
+import { type SeedState } from './setup.ts';
+/** The `opticliSandbox` option: the page each worker makes for its tests' content. */
+export interface SandboxOptions {
+    /** Where: a ref, or "$id" of a step in the seed plan. */
+    parent: ContentRef;
+    /** A page type its parent allows, that allows the test pages below it. */
+    type: string;
+    /** Values for it, such as `{ PageVisibleInMenu: false }` to keep it out of menus. */
+    properties?: Properties;
+}
+/** The options to set in playwright.config's `use`: `defineConfig<{}, OptiCliWorkerOptions>({ use: { opticliSandbox: ... } })`. */
+export type OptiCliWorkerOptions = {
+    opticliSandbox?: SandboxOptions;
+};
+export interface CreatedPage extends WriteResult {
+    /** The page's URL (host-relative), for `page.goto`; for a draft, where it will be once published. */
+    url: string;
+}
+/** Writes that a test's content gets, undone after the test. */
+export declare class Cms {
+    readonly opticli: OptiCli;
+    /** Where {@link page} creates content unless given a parent: the worker's sandbox. */
+    readonly parent: ContentRef | undefined;
+    private readonly created;
+    constructor(opticli: OptiCli, 
+    /** Where {@link page} creates content unless given a parent: the worker's sandbox. */
+    parent: ContentRef | undefined);
+    /** Creates a page, published unless `publish: false`, and removes it after the test. */
+    page(type: string, name: string, properties?: Properties, options?: WriteOptions & {
+        parent?: ContentRef;
+    }): Promise<CreatedPage>;
+    /** Saves a draft of the change unless `publish`. On seeded content, the next run's seed puts it back. */
+    set(ref: ContentRef, properties: Properties, options?: WriteOptions): Promise<WriteResult>;
+    /** Publishes the latest version, or the version `ref` names (`123_456`). */
+    publish(ref: ContentRef): Promise<WriteResult>;
+    /** Runs a plan; what it creates below existing content is removed after the test. */
+    apply(plan: Plan, options?: Parameters<OptiCli['apply']>[1]): Promise<ApplyResult>;
+    /** Deletes what the test made, newest first. Content below other tracked content goes with it. */
+    cleanup(): Promise<void>;
+    private track;
+}
+type TestFixtures = {
+    cms: Cms;
+};
+type WorkerFixtures<Id extends string> = {
+    opticli: OptiCli;
+    seed: SeedState<Id>;
+    sandbox: ContentRef | undefined;
+    opticliSandbox: SandboxOptions | undefined;
+};
+/**
+ * The fixtures, with `seed.refs` and `seed.urls` typed by the seed plan's step ids:
+ * `export const test = createTest<typeof seedPlan>();` (the plan written `as const satisfies Plan`).
+ */
+export declare function createTest<P extends Plan = Plan>(): import("@playwright/test").TestType<import("@playwright/test").PlaywrightTestArgs & import("@playwright/test").PlaywrightTestOptions & TestFixtures, import("@playwright/test").PlaywrightWorkerArgs & import("@playwright/test").PlaywrightWorkerOptions & WorkerFixtures<PlanIds<P> extends never ? string : PlanIds<P>>>;
+export {};

package/lib/playwright/fixtures.js

@@ -0,0 +1,106 @@
+// Playwright fixtures:
+// - `opticli` (worker): the CLI, run as setup ran it.
+// - `seed` (worker): refs and URLs of the seed plan's content.
+// - `sandbox` (worker): with the `opticliSandbox` option, a page per worker that test content goes below; it goes to the
+//   recycle bin when the worker ends, with whatever a failed test left behind.
+// - `cms` (test): writes that are undone after the test.
+// - `baseURL`: the site opticli serves.
+import { test as base } from '@playwright/test';
+import { OptiCli, OptiCliError } from "../opticli.js";
+import { readSeedState } from "./setup.js";
+/** Writes that a test's content gets, undone after the test. */
+export class Cms {
+    opticli;
+    parent;
+    created = [];
+    constructor(opticli, 
+    /** Where {@link page} creates content unless given a parent: the worker's sandbox. */
+    parent) {
+        this.opticli = opticli;
+        this.parent = parent;
+    }
+    /** Creates a page, published unless `publish: false`, and removes it after the test. */
+    async page(type, name, properties = {}, options = {}) {
+        const parent = options.parent ?? this.parent;
+        if (!parent)
+            throw new Error('cms.page() needs a parent: pass { parent }, or set the opticliSandbox option in playwright.config.');
+        const result = await this.opticli.create(parent, type, name, properties, { ...options, publish: options.publish ?? true });
+        this.track(result.ref, parent);
+        if (!result.url)
+            throw new Error(`${type} ${result.ref} has no URL: is ${type} a page type with a template?`);
+        return result;
+    }
+    /** Saves a draft of the change unless `publish`. On seeded content, the next run's seed puts it back. */
+    set(ref, properties, options = {}) {
+        return this.opticli.set(ref, properties, options);
+    }
+    /** Publishes the latest version, or the version `ref` names (`123_456`). */
+    publish(ref) {
+        return this.opticli.publish(ref);
+    }
+    /** Runs a plan; what it creates below existing content is removed after the test. */
+    async apply(plan, options = {}) {
+        const result = await this.opticli.apply(plan, options);
+        for (const step of plan.operations) {
+            if ((step.op === 'create' || step.op === 'block' || step.op === 'upload') && step.id && result.created[step.id]) {
+                this.track(result.created[step.id], step.parent ?? step.for);
+            }
+        }
+        return result;
+    }
+    /** Deletes what the test made, newest first. Content below other tracked content goes with it. */
+    async cleanup() {
+        const errors = [];
+        for (const ref of [...this.created].reverse()) {
+            try {
+                await this.opticli.delete(ref, { ignoreReferences: true });
+            }
+            catch (e) {
+                if (!(e instanceof OptiCliError && e.code === 'not_found'))
+                    errors.push(e);
+            }
+        }
+        this.created.length = 0;
+        if (errors.length)
+            throw new AggregateError(errors, `opticli cleanup: ${errors.length} delete(s) failed`);
+    }
+    track(ref, parent) {
+        // Below tracked or planned ("$id") content: deleting the top item takes it along.
+        if (parent && (parent.startsWith('$') || this.created.includes(parent)))
+            return;
+        this.created.push(ref);
+    }
+}
+/**
+ * The fixtures, with `seed.refs` and `seed.urls` typed by the seed plan's step ids:
+ * `export const test = createTest<typeof seedPlan>();` (the plan written `as const satisfies Plan`).
+ */
+export function createTest() {
+    return base.extend({
+        opticliSandbox: [undefined, { option: true, scope: 'worker' }],
+        seed: [async ({}, use) => use(readSeedState()), { scope: 'worker' }],
+        opticli: [async ({ seed }, use) => use(new OptiCli({ ...seed.opticli, command: [...seed.opticli.command] })), { scope: 'worker' }],
+        sandbox: [
+            async ({ opticli, seed, opticliSandbox }, use, workerInfo) => {
+                if (!opticliSandbox)
+                    return use(undefined);
+                const parent = opticliSandbox.parent.startsWith('$')
+                    ? seed.refs[opticliSandbox.parent.slice(1)]
+                    : opticliSandbox.parent;
+                if (!parent)
+                    throw new Error(`opticliSandbox.parent ${opticliSandbox.parent} is no step id of the seed plan.`);
+                const name = `Playwright worker ${workerInfo.workerIndex} ${new Date().toISOString()}`;
+                const page = await opticli.create(parent, opticliSandbox.type, name, opticliSandbox.properties ?? {}, { publish: true });
+                await use(page.ref);
+                await opticli.delete(page.ref, { ignoreReferences: true });
+            },
+            { scope: 'worker' },
+        ],
+        baseURL: async ({ seed }, use) => use(seed.baseURL),
+        cms: async ({ opticli, sandbox }, use) => {
+            const cms = new Cms(opticli, sandbox);
+            await use(cms);
+            await cms.cleanup();
+        },
+    });
+}

package/lib/playwright/index.d.ts

@@ -0,0 +1,15 @@
+export { Cms, createTest } from './fixtures.ts';
+export type { CreatedPage, OptiCliWorkerOptions, SandboxOptions } from './fixtures.ts';
+export { defineSetup, readSeedState, stateVariable } from './setup.ts';
+export type { SeedState, SetupOptions } from './setup.ts';
+export { OptiCliError } from '../opticli.ts';
+export { expect } from '@playwright/test';
+/** The fixtures, with `seed.refs` keyed by any string; `createTest<typeof plan>()` types them by the plan's ids. */
+export declare const test: import("@playwright/test").TestType<import("@playwright/test").PlaywrightTestArgs & import("@playwright/test").PlaywrightTestOptions & {
+    cms: import("./fixtures.ts").Cms;
+}, import("@playwright/test").PlaywrightWorkerArgs & import("@playwright/test").PlaywrightWorkerOptions & {
+    opticli: import("../opticli.ts").OptiCli;
+    seed: import("./setup.ts").SeedState<string>;
+    sandbox: import("../types.ts").ContentRef | undefined;
+    opticliSandbox: import("./fixtures.ts").SandboxOptions | undefined;
+}>;

package/lib/playwright/index.js

@@ -0,0 +1,8 @@
+// opticli/playwright: start the site, seed content and clean up in Playwright tests.
+import { createTest } from "./fixtures.js";
+export { Cms, createTest } from "./fixtures.js";
+export { defineSetup, readSeedState, stateVariable } from "./setup.js";
+export { OptiCliError } from "../opticli.js";
+export { expect } from '@playwright/test';
+/** The fixtures, with `seed.refs` keyed by any string; `createTest<typeof plan>()` types them by the plan's ids. */
+export const test = createTest();

package/lib/playwright/setup.d.ts

@@ -0,0 +1,50 @@
+import { type OptiCliOptions } from '../opticli.ts';
+import type { ContentRef, Plan } from '../types.ts';
+export interface SetupOptions {
+    /**
+     * Content the tests read, applied with `--update-existing` on every run: the first run creates it, later ones only
+     * repair what changed. Give it a `guidNamespace`, and an `id` on every create, block and upload.
+     */
+    plan?: Plan;
+    /** Where the plan's files (`upload`, `"@file"` values) are; they must be inside it. Default: the working directory. */
+    planDir?: string;
+    /** Publish what the plan saves. Default: true. */
+    publish?: boolean;
+    /** Build the site before starting it (`serve --build`). Default: `OPTICLI_BUILD=1`. */
+    build?: boolean;
+    /** Leave a site that setup started running after the tests. Default: `OPTICLI_KEEP_SITE=1`. */
+    keepSite?: boolean;
+    /** How to run opticli, and which project. */
+    opticli?: Pick<OptiCliOptions, 'command' | 'project' | 'cwd'>;
+}
+/** What setup hands the workers, in {@link stateVariable}. */
+export interface SeedState<Id extends string = string> {
+    /** Where the browser reaches the site. */
+    baseURL: string;
+    /** How setup ran opticli, so the workers run the same. */
+    opticli: {
+        command: readonly string[];
+        project?: string;
+        cwd?: string;
+    };
+    /** The plan's step `id` → content ref. */
+    refs: Record<Id, ContentRef>;
+    /** The plan's step `id` → its URL, host-relative, for content that has one (pages, media). */
+    urls: Partial<Record<Id, string>>;
+}
+/** The environment variable that carries the {@link SeedState} from setup to the workers. */
+export declare const stateVariable = "OPTICLI_PLAYWRIGHT_STATE";
+/**
+ * Playwright's `globalSetup`:
+ *
+ * ```ts
+ * // global-setup.ts
+ * export default defineSetup({ plan: seedPlan, planDir: import.meta.dirname });
+ * ```
+ *
+ * It reuses a site that runs already (`opticli serve`, IDE mode) and leaves it running; a site it starts, it stops
+ * after the tests.
+ */
+export declare function defineSetup(options?: SetupOptions): () => Promise<() => Promise<void>>;
+/** The workers' copy of what setup did. */
+export declare function readSeedState<Id extends string = string>(): SeedState<Id>;

package/lib/playwright/setup.js

@@ -0,0 +1,75 @@
+// Playwright's globalSetup: start the site, check opticli's version, apply the seed plan, and hand what the workers need
+// to them through the environment. It returns the teardown, which Playwright runs after the tests.
+import { compareVersions, OptiCli } from "../opticli.js";
+import { requiredOpticli } from "../version.js";
+/** The environment variable that carries the {@link SeedState} from setup to the workers. */
+export const stateVariable = 'OPTICLI_PLAYWRIGHT_STATE';
+/**
+ * Playwright's `globalSetup`:
+ *
+ * ```ts
+ * // global-setup.ts
+ * export default defineSetup({ plan: seedPlan, planDir: import.meta.dirname });
+ * ```
+ *
+ * It reuses a site that runs already (`opticli serve`, IDE mode) and leaves it running; a site it starts, it stops
+ * after the tests.
+ */
+export function defineSetup(options = {}) {
+    return async () => {
+        const opticli = new OptiCli({
+            ...options.opticli,
+            onWarnings: (warnings, args) => console.warn(`opticli ${args[0]}: ${warnings.join(' ')}`),
+        });
+        const before = await opticli.serveStatus();
+        const served = await opticli.serve({ build: options.build ?? process.env.OPTICLI_BUILD === '1' });
+        checkVersions(served.meta.version, served.data.agent?.version);
+        const baseURL = served.data.browseUrl ?? served.data.url;
+        if (!baseURL)
+            throw new Error(`opticli serve gave no URL: ${JSON.stringify(served.data)}`);
+        const state = {
+            baseURL,
+            opticli: { command: opticli.command, project: opticli.project, cwd: opticli.cwd },
+            refs: {},
+            urls: {},
+        };
+        if (options.plan) {
+            const applied = await opticli.apply(options.plan, {
+                baseDir: options.planDir,
+                updateExisting: true,
+                publish: options.publish ?? true,
+            });
+            state.refs = applied.created;
+            for (const step of applied.operations) {
+                if (step.id && step.result?.url)
+                    state.urls[step.id] = step.result.url;
+            }
+            const changed = applied.operations.filter((o) => o.status !== 'unchanged').length;
+            console.log(`opticli: seed plan ${changed ? `changed ${changed} of ${applied.operations.length} steps` : 'unchanged'}`);
+        }
+        process.env[stateVariable] = JSON.stringify(state);
+        const startedSite = before.state !== 'running';
+        return async () => {
+            if (startedSite && !(options.keepSite ?? process.env.OPTICLI_KEEP_SITE === '1'))
+                await opticli.serveStop();
+        };
+    };
+}
+/** The workers' copy of what setup did. */
+export function readSeedState() {
+    const json = process.env[stateVariable];
+    if (!json) {
+        throw new Error("No opticli setup ran: set globalSetup in playwright.config to a file that exports defineSetup() from '@epinova/opticli/playwright'.");
+    }
+    return JSON.parse(json);
+}
+function checkVersions(cli, agent) {
+    const upgrade = 'dotnet tool update -g OptiCli (or dotnet tool update OptiCli where a tool manifest pins it)';
+    if (compareVersions(cli, requiredOpticli) < 0) {
+        throw new Error(`This package needs opticli ${requiredOpticli} or newer; ${cli} runs. Upgrade it: ${upgrade}.`);
+    }
+    if (agent && compareVersions(agent, requiredOpticli) < 0) {
+        throw new Error(`The site runs the site agent of opticli ${agent}, older than ${requiredOpticli}. ` +
+            'Restart it (opticli serve --stop, or restart it in the IDE) so it runs the agent of the installed opticli.');
+    }
+}