@potential-guide/pguide-task-engine 0.0.0-stage → 0.1.0-rc.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 shazhou-ww
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,75 @@
-# Temporary Holding Version
+# pguide task-engine
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Install `@potential-guide/pguide-task-engine` beside `pguide`, with its
+`pguide-task-engine` executable on PATH (or in pguide commandDirectories).
+It implements the existing `pguide-command-v1` discovery protocol. No automatic
+settings registration or user configuration writes occur.
+
+```powershell
+pguide task-engine --no-global-config --port 0 --database .\new-tasks.sqlite --ipfs-gateway-url http://127.0.0.1:8080
+pguide-task-engine --config .\server.yaml --ui
+pguide task-engine --help --format json
+```
+
+Provide an explicit read-only Trustless Gateway URL through CLI, the specified
+YAML/JSON file or `task-engine.ipfsGatewayUrl` in user settings. There is no default
+node or public Gateway, RPC selection or fallback. Author publishing/pinning is unchanged.
+**Breaking change:** remove `ipfsRpcUrl` / `ipfsTransport`, their `task-engine.`
+setting IDs and old flags; use `--ipfs-gateway-url` instead. Old fields fail even
+when overridden. User files are never automatically rewritten.
+`--help` prints the actual platform-specific pguide user configuration path,
+defaults, all options and boundary rules without opening a DB, listener or Gateway
+connection. See [the configuration guide](../../docs/task-server.md).
+
+The package depends on the public Web UI application package, including its
+server runtime and browser assets; no source-checkout/private-app dependency is
+required. Without `--ui` no UI listener is started. Engine/UI communicate through
+public HTTP, not an Engine object or SQLite access.
+
+The package-owned `objectives.yaml` permits `@potential-guide/task-sdk` only for
+the existing development dependency that authors standard Bundle fixtures in
+service tests, following the Web UI application's declaration. It is not a
+production dependency or a service runtime import; no repository-wide dependency
+exception is required.
+
+## Real local Kubo end-to-end verification
+
+The opt-in integration test uses the repository's actual `pguide` discovery and
+command executables, not a mock IPFS client or an npm tarball. From the repository
+root, after installing dependencies:
+
+```powershell
+pnpm exec turbo run build --filter=@potential-guide/pguide-task-engine... --filter=@potential-guide/pguide-task-bundle... --filter=pguide...
+$env:PGUIDE_E2E_KUBO_RPC = 'http://127.0.0.1:5001'
+$env:PGUIDE_E2E_KUBO_GATEWAY = 'http://127.0.0.1:8080'
+pnpm exec tsx --test apps\pguide-task-engine\test\kubo.e2e.test.ts
+```
+
+Both URLs must be explicitly supplied; without them the test is skipped. Use an
+already running, caller-managed Kubo whose RPC permits CAR imports and whose
+Gateway serves raw blocks. The test never starts/stops Kubo or edits its
+configuration. It imports and **recursively pins** its generated CAR with
+`POST /api/v0/dag/import?pin-roots=true`; imported roots remain pinned afterward,
+including roots imported before a later assertion fails. It never removes pins
+from the shared node. Only run it when these writes are authorized.
+
+The test initializes a separate author package, reuses the repository's installed
+SDK/TypeBox dependencies, builds and checks the CAR, imports it into real Kubo,
+and runs a CLI-owned Engine against the Gateway. It verifies streamed Bundle
+resource reads, a business-created JSON file, the completed Task/Run result,
+`run.started`, `run.dispatched`, `run.progress`, `run.outcome`, `run.exited`,
+`run.reclaimed` history and diagnostic logs. Restarting with the same SQLite DB
+must preserve the result/history/logs and return the same Task for a repeated
+Request. An outcome report is not itself a terminal Task: completion is checked
+after physical Worker exit and reclamation.
+
+Each Engine uses a private DB and a random loopback port. Ready diagnostics
+include its URL and PID. A test launcher records the owned service PID before
+startup, so even a readiness timeout can terminate the actual service rather
+than just the dispatching CLI. All owned CLI processes and temporary author/DB files
+are cleaned up; the shared Kubo remains running. Windows process termination is
+forced, so the test waits for Worker reclamation before stopping its Engine.
+It does not claim to verify graceful Windows OS signal delivery.
+Optionally set `PGUIDE_E2E_REPORT` to an absolute, writable JSON filename to retain
+the CID, Request/Task/Run IDs, endpoints/PIDs, observed events/logs and exact
+business artifact content after temporary files and services have been removed.

package/dist/config.d.ts

@@ -0,0 +1,26 @@
+export interface ServiceConfig {
+    host: string;
+    port: number;
+    database: string;
+    ipfsGatewayUrl: string;
+    scope: string;
+    ui: boolean;
+    uiOptions: {
+        host: string;
+        port: number;
+        favoritesFile: string;
+    };
+}
+export declare class ConfigurationError extends Error {
+}
+/** Validate every provided value before replacing complete settings across layers. */
+export declare function validateLayer(value: unknown, base: string, source: string): Partial<ServiceConfig>;
+export declare function parseArguments(argv: readonly string[]): {
+    options: import("@potential-guide/cli-core").GlobalOptions;
+    cli: Record<string, unknown>;
+    configFile: string | undefined;
+    global: boolean;
+};
+export declare function resolveConfig(parsed: ReturnType<typeof parseArguments>): Promise<ServiceConfig>;
+export declare function requireGateway(config: Partial<ServiceConfig>): void;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAWA,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,EAAE,EAAE,OAAO,CAAC;IACZ,SAAS,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC;CAClE;AACD,qBAAa,kBAAmB,SAAQ,KAAK;CAAG;AA2BhD,sFAAsF;AACtF,wBAAgB,aAAa,CAC3B,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,aAAa,CAAC,CA2DxB;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE;;;;;EAiDrD;AAED,wBAAsB,aAAa,CACjC,MAAM,EAAE,UAAU,CAAC,OAAO,cAAc,CAAC,GACxC,OAAO,CAAC,aAAa,CAAC,CAoExB;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG,IAAI,CAKnE"}

package/dist/config.js

@@ -0,0 +1,225 @@
+import { readFile } from "node:fs/promises";
+import { dirname, extname, resolve } from "node:path";
+import { extractGlobals, loadConfig, parseConfig, parseJsonc, userConfigPath, } from "@potential-guide/cli-core";
+import { parseDocument } from "yaml";
+export class ConfigurationError extends Error {
+}
+const fields = new Set(["host", "port", "database", "ipfsGatewayUrl", "scope", "ui", "uiOptions"]);
+const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+function invalid(source, field) {
+    // Never include values, parser excerpts or URLs in diagnostics.
+    throw new ConfigurationError(`Invalid ${field} in ${source}.`);
+}
+function retired(source) {
+    throw new ConfigurationError(`RPC/transport service configuration is retired in ${source}. Remove ipfsRpcUrl/ipfsTransport (including task-engine. setting IDs) and --ipfs-rpc-url/--ipfs-transport; migrate to ipfsGatewayUrl or --ipfs-gateway-url with an explicit read-only Gateway URL.`);
+}
+function host(value, source) {
+    if (!["127.0.0.1", "localhost", "::1"].includes(value))
+        invalid(source, "host");
+    return value === "localhost" ? "127.0.0.1" : value;
+}
+function port(value, source) {
+    if (!Number.isInteger(value) || value < 0 || value > 65535)
+        invalid(source, "port");
+    return value;
+}
+function path(value, base, source) {
+    if (typeof value !== "string" || !value.trim() || value.includes("\0"))
+        invalid(source, "path");
+    return resolve(base, value);
+}
+/** Validate every provided value before replacing complete settings across layers. */
+export function validateLayer(value, base, source) {
+    if (!object(value))
+        invalid(source, "configuration");
+    const result = {};
+    for (const [key, entry] of Object.entries(value)) {
+        if (key === "ipfsRpcUrl" || key === "ipfsTransport")
+            retired(source);
+        if (!fields.has(key))
+            invalid(source, "unknown service field");
+        switch (key) {
+            case "host":
+                result.host = host(entry, source);
+                break;
+            case "port":
+                result.port = port(entry, source);
+                break;
+            case "database":
+                result.database = path(entry, base, source);
+                break;
+            case "ipfsGatewayUrl": {
+                let url;
+                try {
+                    if (typeof entry !== "string")
+                        invalid(source, key);
+                    url = new URL(entry);
+                }
+                catch {
+                    invalid(source, key);
+                }
+                if (!["http:", "https:"].includes(url.protocol) ||
+                    url.username ||
+                    url.password ||
+                    url.href.includes("?") ||
+                    url.href.includes("#"))
+                    invalid(source, key);
+                result[key] = url.href;
+                break;
+            }
+            case "scope":
+                if (typeof entry !== "string" || !/^[a-zA-Z0-9_-]{1,64}$/.test(entry))
+                    invalid(source, key);
+                result.scope = entry;
+                break;
+            case "ui":
+                if (typeof entry !== "boolean")
+                    invalid(source, key);
+                result.ui = entry;
+                break;
+            case "uiOptions":
+                if (!object(entry) ||
+                    Object.keys(entry).length !== 3 ||
+                    !["host", "port", "favoritesFile"].every((name) => Object.hasOwn(entry, name)))
+                    invalid(source, key);
+                result.uiOptions = {
+                    host: host(entry.host, source),
+                    port: port(entry.port, source),
+                    favoritesFile: path(entry.favoritesFile, base, source),
+                };
+                break;
+        }
+    }
+    return result;
+}
+export function parseArguments(argv) {
+    const { options, rest } = extractGlobals(argv, { serviceConfig: true });
+    const cli = {};
+    const seen = new Set();
+    let configFile;
+    let global = true;
+    const names = {
+        "--host": "host",
+        "--port": "port",
+        "--database": "database",
+        "--ipfs-gateway-url": "ipfsGatewayUrl",
+        "--scope": "scope",
+        "--ui-options": "uiOptions",
+    };
+    for (let index = 0; index < rest.length; index++) {
+        const raw = rest[index];
+        const equals = raw.indexOf("=");
+        const flag = equals < 0 ? raw : raw.slice(0, equals);
+        if (flag === "--ipfs-rpc-url" || flag === "--ipfs-transport")
+            retired("CLI");
+        const key = flag === "--no-ui" ? "--ui" : flag;
+        if (seen.has(key))
+            throw new ConfigurationError("Repeated service option.");
+        seen.add(key);
+        if (["--ui", "--no-ui", "--no-global-config"].includes(flag)) {
+            if (equals >= 0)
+                throw new ConfigurationError("Boolean switches do not take values.");
+            if (flag === "--no-global-config")
+                global = false;
+            else
+                cli.ui = flag === "--ui";
+            continue;
+        }
+        if (flag !== "--config" && !Object.hasOwn(names, flag))
+            throw new ConfigurationError("Unknown service option.");
+        const value = equals < 0 ? rest[++index] : raw.slice(equals + 1);
+        if (!value || value.startsWith("--"))
+            throw new ConfigurationError("Service option requires a value.");
+        if (flag === "--config")
+            configFile = resolve(options.cwd, value);
+        else {
+            const field = names[flag];
+            if (field === "port") {
+                if (!/^\d+$/.test(value))
+                    invalid("CLI", field);
+                cli[field] = Number(value);
+            }
+            else if (field === "uiOptions") {
+                try {
+                    cli[field] = JSON.parse(value);
+                }
+                catch {
+                    invalid("CLI", field);
+                }
+            }
+            else
+                cli[field] = value;
+        }
+    }
+    return { options, cli, configFile, global };
+}
+export async function resolveConfig(parsed) {
+    const cwd = parsed.options.cwd;
+    const defaults = {
+        host: "127.0.0.1",
+        port: 3000,
+        database: resolve(cwd, "tasks.sqlite"),
+        scope: "local",
+        ui: false,
+        uiOptions: {
+            host: "127.0.0.1",
+            port: 4310,
+            favoritesFile: resolve(cwd, "task-favorites.json"),
+        },
+    };
+    let user = {};
+    if (parsed.global) {
+        try {
+            const userPath = userConfigPath();
+            const text = await readFile(userPath, "utf8").catch((error) => {
+                if (error.code === "ENOENT")
+                    return "{}";
+                throw error;
+            });
+            // Validate explicit service fields before catalog validation: old registrations
+            // may omit retired IDs or conflict with the bundled settings description.
+            user = validateLayer(Object.fromEntries(Object.entries(parseConfig(text))
+                .filter(([id]) => id.startsWith("task-engine."))
+                .map(([id, value]) => [id.slice(12), value])), dirname(userPath), "pguide user config");
+            await loadConfig(cwd, [], { project: false });
+        }
+        catch (error) {
+            if (error instanceof ConfigurationError)
+                throw error;
+            throw new ConfigurationError("Cannot read or validate pguide user configuration/settings registry.");
+        }
+    }
+    let file = {};
+    if (parsed.configFile) {
+        const extension = extname(parsed.configFile).toLowerCase();
+        if (![".yaml", ".yml", ".json"].includes(extension))
+            throw new ConfigurationError("Service --config requires YAML/JSON data. Executable .mjs configs are retired; migrate to declarative fields.");
+        let value;
+        try {
+            const text = await readFile(parsed.configFile, "utf8");
+            if (extension === ".json") {
+                value = JSON.parse(text);
+                parseJsonc(text);
+            }
+            else {
+                const document = parseDocument(text, { uniqueKeys: true });
+                if (document.errors.length || document.warnings.length)
+                    invalid("service file", "YAML");
+                value = document.toJS({ maxAliasCount: 0 });
+            }
+        }
+        catch {
+            throw new ConfigurationError("Cannot read or parse service YAML/JSON file.");
+        }
+        file = validateLayer(value, dirname(parsed.configFile), "service file");
+    }
+    const cli = validateLayer(parsed.cli, cwd, "CLI");
+    const final = { ...defaults, ...user, ...file, ...cli };
+    requireGateway(final);
+    return validateLayer(final, cwd, "effective configuration");
+}
+export function requireGateway(config) {
+    if (!config.ipfsGatewayUrl)
+        throw new ConfigurationError("Service requires an explicit ipfsGatewayUrl; provide --ipfs-gateway-url or task-engine.ipfsGatewayUrl. No default Gateway is selected.");
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/main.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=main.d.ts.map

package/dist/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":""}

package/dist/main.js

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+import { userConfigPath } from "@potential-guide/cli-core";
+import { ConfigurationError, parseArguments, resolveConfig } from "./config.js";
+const metadata = {
+    protocol: "pguide-command-v1",
+    command: "task-engine",
+    version: "0.1.0-rc.0",
+    description: "Start a foreground loopback Task Engine, optionally with its HTTP Web UI.",
+};
+async function main() {
+    const argv = process.argv.slice(2);
+    if (argv.length === 1 && argv[0] === "--pguide-command-metadata") {
+        console.log(JSON.stringify(metadata));
+        return;
+    }
+    const parsed = parseArguments(argv.map((arg) => (arg === "-h" ? "--help" : arg)));
+    if (parsed.options.help) {
+        const help = {
+            schemaVersion: 1,
+            command: "task-engine",
+            usage: "pguide task-engine [--config server.yaml|server.json] [options]",
+            options: [
+                "--host <127.0.0.1|localhost|::1>",
+                "--port <0..65535>",
+                "--database <path>",
+                "--ipfs-gateway-url <HTTP(S) Gateway base URL; required from an enabled source>",
+                "--scope <local-scope>",
+                "--ui",
+                "--no-ui",
+                '--ui-options \'{"host":"127.0.0.1","port":4310,"favoritesFile":"favorites.json"}\'',
+                "--no-global-config",
+                "--cwd <directory>",
+                "--help",
+                "--format json",
+            ],
+            precedence: "Explicit CLI > explicit YAML/JSON file > pguide USER config.jsonc > defaults. Project service settings are never read.",
+            globalConfig: userConfigPath(),
+            paths: "Effective CWD is --cwd or process CWD for both entrypoints and --config. Each file's paths are relative to that file; CLI paths are relative to effective CWD.",
+            validation: "Every provided layer is validated even when overridden. Complete settings (including uiOptions) replace, never deep merge. No executable config or environment service overrides.",
+            isolation: "--no-global-config skips the user main file, including top-level discovery and user commandDirectories. PATH and project discovery remain available.",
+            defaults: {
+                host: "127.0.0.1",
+                port: 3000,
+                database: "tasks.sqlite",
+                scope: "local",
+                ui: false,
+                uiOptions: { host: "127.0.0.1", port: 4310, favoritesFile: "task-favorites.json" },
+            },
+            security: "No token; fixed loopback only (localhost becomes 127.0.0.1; ::1 supported). Caller local-cli is limited to the configured scope. Host/Origin/fetch-site, GET/POST and JSON writes are checked. Do not expose through a proxy. Other local users/processes are not isolated.",
+            lifecycle: "Foreground only. Stops only this invocation's Engine/UI on SIGINT/SIGTERM. Never starts, stops or manages Kubo. No UI unless --ui. Old .mjs configs must be manually migrated. Gateway-only: an explicit URL is required (no credentials/query/fragment); no default node or public Gateway. Base paths are appended with /ipfs/{cid}?format=raw. Raw blocks only, no redirects, 2 MiB/block and 30 s/read. No service RPC or transport selection/fallback; author publishing/pinning is unchanged.",
+        };
+        console.log(parsed.options.format === "json"
+            ? JSON.stringify(help)
+            : `${help.usage}\n${help.options.join("\n")}\n\n${help.precedence}\nUser config: ${help.globalConfig}\n${help.paths}\n${help.validation}\n${help.isolation}\nDefaults: ${JSON.stringify(help.defaults)}\n${help.security}\n${help.lifecycle}`);
+        return;
+    }
+    if (parsed.options.version) {
+        console.log(metadata.version);
+        return;
+    }
+    const config = await resolveConfig(parsed);
+    const { startService } = await import("./service.js");
+    const service = await startService(config);
+    console.log(JSON.stringify({ event: "ready", url: service.url, uiUrl: service.uiUrl, pid: process.pid }));
+    let stopping = false;
+    const shutdown = () => {
+        if (stopping)
+            return;
+        stopping = true;
+        void service.close().then(() => {
+            process.removeListener("SIGINT", shutdown);
+            process.removeListener("SIGTERM", shutdown);
+            console.log(JSON.stringify({ event: "closed" }));
+        }, () => {
+            console.error("Shutdown failed; physical cleanup unconfirmed.");
+            process.exit(1);
+        });
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+}
+void main().catch((error) => {
+    // Errors from libraries can contain URL credentials or config excerpts.
+    console.error(error instanceof ConfigurationError
+        ? error.message
+        : "Invalid configuration or service startup failed; cleanup unconfirmed.");
+    process.exit(1);
+});
+//# sourceMappingURL=main.js.map

package/dist/main.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.js","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":"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"}

package/dist/service.d.ts

@@ -0,0 +1,12 @@
+import { type Authorize, type Caller } from "@potential-guide/task-protocol";
+import { type ServiceConfig } from "./config.js";
+export declare function localPolicy(scope: string, origin: () => string): {
+    authorize: Authorize;
+    resolveCaller(request: Request): Caller;
+};
+export declare function startService(raw: ServiceConfig): Promise<{
+    close(): Promise<void>;
+    uiUrl?: string;
+    url: string;
+}>;
+//# sourceMappingURL=service.d.ts.map

package/dist/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,KAAK,SAAS,EACd,KAAK,MAAM,EAGZ,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAkB,KAAK,aAAa,EAAiB,MAAM,aAAa,CAAC;AAchF,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,MAAM;;2BASpC,OAAO,GAAG,MAAM;EAiB1C;AAED,wBAAsB,YAAY,CAAC,GAAG,EAAE,aAAa;aAwCxC,OAAO,CAAC,IAAI,CAAC;;;GAkBzB"}

package/dist/service.js

@@ -0,0 +1,106 @@
+import { createIpfsGatewayClient } from "@potential-guide/task-engine";
+import { startTaskServer } from "@potential-guide/task-engine-server";
+import { startUiServer, validateUiConfig } from "@potential-guide/task-engine-webui/server";
+import { TaskError, } from "@potential-guide/task-protocol";
+import { requireGateway, validateLayer } from "./config.js";
+const operations = new Set([
+    "submit",
+    "request",
+    "task",
+    "run",
+    "cancel",
+    "history",
+    "subscribe",
+    "list",
+    "list-runs",
+    "message",
+]);
+export function localPolicy(scope, origin) {
+    const caller = Object.freeze({ subject: "local-cli", scope });
+    const authorize = (identity, operation, target) => identity.subject === caller.subject &&
+        identity.scope === scope &&
+        target === scope &&
+        operations.has(operation);
+    return {
+        authorize,
+        resolveCaller(request) {
+            const expected = origin();
+            const site = request.headers.get("sec-fetch-site");
+            if (!expected ||
+                request.headers.get("host") !== new URL(expected).host ||
+                (request.headers.has("origin") && request.headers.get("origin") !== expected) ||
+                (site !== null && site !== "same-origin" && site !== "none") ||
+                !["GET", "POST"].includes(request.method) ||
+                (request.method === "POST" &&
+                    request.headers.get("content-type")?.split(";")[0]?.trim().toLowerCase() !==
+                        "application/json"))
+                throw new TaskError("forbidden", "Local service request policy denied access.");
+            return caller;
+        },
+    };
+}
+export async function startService(raw) {
+    const config = validateLayer(raw, process.cwd(), "effective configuration");
+    requireGateway(config);
+    const uiConfig = {
+        ...config.uiOptions,
+        endpoints: [
+            { id: "local", label: "Local Task Engine", binding: config.scope, url: "http://127.0.0.1:1" },
+        ],
+    };
+    // All declarative options are checked before any DB or listening socket is opened.
+    validateUiConfig(uiConfig);
+    let origin = "";
+    const policy = localPolicy(config.scope, () => origin);
+    const server = await startTaskServer({
+        host: config.host,
+        port: config.port,
+        database: config.database,
+        ipfsClient: createIpfsGatewayClient(config.ipfsGatewayUrl),
+        ...policy,
+    });
+    origin = server.url;
+    let ui;
+    try {
+        if (config.ui)
+            ui = await startUiServer({
+                ...uiConfig,
+                endpoints: [{ ...uiConfig.endpoints[0], url: server.url }],
+            });
+    }
+    catch (error) {
+        try {
+            await server.close();
+        }
+        catch {
+            throw new Error("UI startup and Engine rollback failed; cleanup unconfirmed.");
+        }
+        throw error;
+    }
+    let closing;
+    return {
+        url: server.url,
+        ...(ui ? { uiUrl: ui.url } : {}),
+        close() {
+            closing ??= (async () => {
+                const failures = [];
+                try {
+                    await ui?.close();
+                }
+                catch (error) {
+                    failures.push(error);
+                }
+                try {
+                    await server.close();
+                }
+                catch (error) {
+                    failures.push(error);
+                }
+                if (failures.length)
+                    throw new Error("Service cleanup unconfirmed.");
+            })();
+            return closing;
+        },
+    };
+}
+//# sourceMappingURL=service.js.map

package/dist/service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.js","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@potential-guide/pguide-task-engine",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0-rc.0",
+  "description": "Declarative local Task Engine service command with optional Web UI.",
+  "type": "module",
+  "bin": {
+    "pguide-task-engine": "./dist/main.js"
+  },
+  "pguide": {
+    "settings": "./settings.json"
+  },
+  "files": [
+    "dist",
+    "settings.json",
+    "README.md"
+  ],
+  "dependencies": {
+    "yaml": "2.9.1",
+    "@potential-guide/task-engine-webui": "^0.1.0-rc.0",
+    "@potential-guide/task-protocol": "^0.1.0-rc.0",
+    "@potential-guide/task-engine": "^0.1.0-rc.0",
+    "@potential-guide/task-engine-server": "^0.1.0-rc.0",
+    "@potential-guide/cli-core": "^0.3.0-rc.0"
+  },
+  "devDependencies": {
+    "@potential-guide/task-sdk": "^0.1.0-rc.0",
+    "@potential-guide/pguide-task-bundle": "^0.1.0-rc.0"
+  },
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shazhou-ww/potential-guide.git",
+    "directory": "apps/pguide-task-engine"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "biome lint .",
+    "test": "tsx --test \"test/*.test.ts\"",
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\""
+  }
 }

package/settings.json

@@ -0,0 +1,43 @@
+{
+  "schemaVersion": 1,
+  "namespace": "task-engine",
+  "settings": {
+    "task-engine.host": {
+      "description": "Fixed loopback binding; localhost normalizes to 127.0.0.1.",
+      "schema": { "enum": ["127.0.0.1", "localhost", "::1"] }
+    },
+    "task-engine.port": {
+      "description": "Engine TCP port; zero selects an available port.",
+      "schema": { "type": "integer", "minimum": 0, "maximum": 65535 }
+    },
+    "task-engine.database": {
+      "description": "SQLite filename, relative to the source file directory.",
+      "schema": { "type": "string", "minLength": 1 }
+    },
+    "task-engine.ipfsGatewayUrl": {
+      "description": "Required explicit read-only HTTP(S) Trustless Gateway base URL; no credentials, query or fragment. No default node.",
+      "schema": { "type": "string", "minLength": 1 }
+    },
+    "task-engine.scope": {
+      "description": "Single local Caller scope. Other scopes are denied.",
+      "schema": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,64}$" }
+    },
+    "task-engine.ui": {
+      "description": "Start the HTTP-only local Web UI.",
+      "schema": { "type": "boolean" }
+    },
+    "task-engine.uiOptions": {
+      "description": "Whole UI setting, replaced rather than deep merged. All properties required.",
+      "schema": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["host", "port", "favoritesFile"],
+        "properties": {
+          "host": { "enum": ["127.0.0.1", "localhost", "::1"] },
+          "port": { "type": "integer", "minimum": 0, "maximum": 65535 },
+          "favoritesFile": { "type": "string", "minLength": 1 }
+        }
+      }
+    }
+  }
+}