@sfship/plugin-ship 1.0.0-beta.2

package/lib/core/service.github.js

@@ -0,0 +1,270 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/* eslint-disable camelcase */
+import { join } from 'node:path';
+import { parse } from 'yaml';
+import { ensureDir, writeBinary } from './file.js';
+import { getToken, setToken } from './service.js';
+import { ExpectedError } from './error.js';
+const SERVICE = 'github';
+/** Returns the stored GitHub access token for the given alias, or `undefined` if not connected. */
+export function getGithubToken(alias = 'default') {
+    return getToken(SERVICE, alias) ?? undefined;
+}
+/**
+ * Persists a GitHub access token securely for the given alias.
+ * The token is stored in the OS keychain; metadata is written alongside it.
+ */
+export function setGithubToken(token, username, alias = 'default', scopes = []) {
+    setToken(SERVICE, username, alias, token, scopes);
+}
+// ---- URL utilities -----------------------------------------------------------
+/** Normalises a GitHub reference to an `owner/repo` slug, accepting full URLs or slugs. */
+export function normalizeRepo(github) {
+    return github.replace(/^https?:\/\/github\.com\//, '').replace(/\.git$/, '');
+}
+// ---- Internal ----------------------------------------------------------------
+function githubHeaders() {
+    const token = getGithubToken();
+    const headers = { Accept: 'application/vnd.github+json' };
+    if (token)
+        headers['Authorization'] = `Bearer ${token}`;
+    return headers;
+}
+/** Fetches the authenticated user and their granted OAuth scopes. */
+export async function fetchGithubUser(token) {
+    const resp = await fetch('https://api.github.com/user', {
+        headers: { Authorization: `Bearer ${token}`, 'User-Agent': 'plugin-ship' },
+    });
+    const user = (await resp.json());
+    const scopes = (resp.headers.get('x-oauth-scopes') ?? '')
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean);
+    return { user, scopes };
+}
+// ---- API helpers -------------------------------------------------------------
+/**
+ * Fetches a GitHub release for `repo`. Returns `null` if no release exists.
+ * When `tag` is provided, fetches that specific release.
+ * When `prerelease` is true, fetches the latest pre-release; otherwise fetches the latest production release.
+ */
+export async function fetchRelease(repo, tag, prerelease = false) {
+    if (prerelease && !tag) {
+        const res = await fetch(`https://api.github.com/repos/${repo}/releases?per_page=100`, {
+            headers: githubHeaders(),
+        });
+        if (!res.ok)
+            return null;
+        const releases = (await res.json());
+        const found = releases.find((r) => r.prerelease);
+        return found ? { tagName: found.tag_name } : null;
+    }
+    const url = tag
+        ? `https://api.github.com/repos/${repo}/releases/tags/${encodeURIComponent(tag)}`
+        : `https://api.github.com/repos/${repo}/releases/latest`;
+    const res = await fetch(url, { headers: githubHeaders() });
+    if (res.status === 404)
+        return null;
+    if (!res.ok)
+        throw new ExpectedError(`Failed to fetch release for ${repo}: ${res.statusText}`);
+    const data = (await res.json());
+    return { tagName: data.tag_name };
+}
+/** Fetches raw file content from a GitHub repository at a specific ref. Returns `null` if the file does not exist. */
+export async function fetchRaw(repo, ref, filename) {
+    const res = await fetch(`https://raw.githubusercontent.com/${repo}/${ref}/${filename}`);
+    if (res.status === 404)
+        return null;
+    if (!res.ok)
+        throw new ExpectedError(`Failed to fetch ${filename} from ${repo}@${ref}: ${res.statusText}`);
+    return res.text();
+}
+/**
+ * Fetches the annotated git tag object for `tagName` in `repo`.
+ * Returns `null` for lightweight tags (no message) or if the tag does not exist.
+ */
+export async function fetchGitTag(repo, tagName) {
+    const refRes = await fetch(`https://api.github.com/repos/${repo}/git/refs/tags/${encodeURIComponent(tagName)}`, {
+        headers: githubHeaders(),
+    });
+    if (!refRes.ok)
+        return null;
+    const ref = (await refRes.json());
+    if (ref.object.type !== 'tag')
+        return null;
+    const tagRes = await fetch(`https://api.github.com/repos/${repo}/git/tags/${ref.object.sha}`, {
+        headers: githubHeaders(),
+    });
+    if (!tagRes.ok)
+        return null;
+    return (await tagRes.json());
+}
+/** Fetches basic repository metadata from the GitHub API using an explicit token. */
+export async function fetchRepoInfo(repo, token) {
+    const resp = await fetch(`https://api.github.com/repos/${repo}`, {
+        headers: { Authorization: `Bearer ${token}`, Accept: 'application/vnd.github+json' },
+    });
+    if (!resp.ok)
+        throw new ExpectedError(`GitHub API error: ${resp.status} ${resp.statusText}`);
+    return (await resp.json());
+}
+/**
+ * Returns the package namespace declared in a CCI repo's `cumulusci.yml` at `ref`.
+ * Returns an empty string if the file is missing or declares no namespace.
+ */
+export async function fetchCciNamespace(repo, ref) {
+    const raw = await fetchRaw(repo, ref, 'cumulusci.yml');
+    if (!raw)
+        return '';
+    const parsed = parse(raw);
+    return parsed?.project?.package?.namespace ?? '';
+}
+/**
+ * Lists the immediate subdirectories of `path` in a GitHub repo at `ref`.
+ * Returns an empty array if the path does not exist.
+ */
+export async function fetchSubdirs(repo, ref, path) {
+    const url = `https://api.github.com/repos/${repo}/contents/${path}?ref=${encodeURIComponent(ref)}`;
+    const res = await fetch(url, { headers: githubHeaders() });
+    if (res.status === 404)
+        return [];
+    if (!res.ok)
+        throw new ExpectedError(`Failed to list ${path} in ${repo}@${ref}: ${res.statusText}`);
+    const entries = (await res.json());
+    return entries.filter((e) => e.type === 'dir').map((e) => `${path}/${e.name}`);
+}
+/** Downloads a GitHub repository directory at `ref` into `localDir`, recursing into subdirectories. */
+export async function downloadDir(repo, ref, remotePath, localDir) {
+    const url = `https://api.github.com/repos/${repo}/contents/${remotePath}?ref=${encodeURIComponent(ref)}`;
+    const res = await fetch(url, { headers: githubHeaders() });
+    if (!res.ok)
+        throw new ExpectedError(`Failed to fetch ${remotePath} from ${repo}@${ref}: ${res.statusText}`);
+    const entries = (await res.json());
+    ensureDir(localDir);
+    await Promise.all(entries.map(async (entry) => {
+        const entryLocal = join(localDir, entry.name);
+        if (entry.type === 'dir') {
+            await downloadDir(repo, ref, entry.path, entryLocal);
+        }
+        else {
+            let buf;
+            if (entry.content && entry.encoding === 'base64') {
+                buf = Buffer.from(entry.content.replace(/\n/g, ''), 'base64');
+            }
+            else if (entry.download_url) {
+                const fileRes = await fetch(entry.download_url, { headers: githubHeaders() });
+                buf = Buffer.from(await fileRes.arrayBuffer());
+            }
+            else {
+                throw new ExpectedError(`Cannot download ${entry.path}: no content or download_url available`);
+            }
+            writeBinary(entryLocal, buf);
+        }
+    }));
+}
+// ---- Authenticated API helper ------------------------------------------------
+/** Authenticated GitHub API call. Throws ExpectedError on non-2xx. */
+export async function gh(token, path, init) {
+    const headers = {
+        Authorization: `Bearer ${token}`,
+        Accept: 'application/vnd.github+json',
+    };
+    if (init?.body !== undefined)
+        headers['Content-Type'] = 'application/json';
+    const resp = await fetch(`https://api.github.com${path}`, {
+        method: init?.method,
+        headers,
+        body: init?.body !== undefined ? JSON.stringify(init.body) : undefined,
+    });
+    if (!resp.ok) {
+        const text = await resp.text();
+        throw new ExpectedError(`GitHub API ${resp.status} ${resp.statusText} on ${path}: ${text}`);
+    }
+    const data = await resp.json();
+    return data;
+}
+/** Returns the SHA of the first commit on the repo's default branch, or null. */
+export async function fetchFirstCommitSha(repo, token) {
+    const headers = { Authorization: `Bearer ${token}`, Accept: 'application/vnd.github+json' };
+    const resp = await fetch(`https://api.github.com/repos/${repo}/commits?per_page=1`, { headers });
+    if (!resp.ok)
+        return null;
+    const linkHeader = resp.headers.get('link');
+    if (!linkHeader) {
+        const data = await resp.json();
+        const commits = data;
+        return commits[0]?.sha ?? null;
+    }
+    const lastMatch = linkHeader.match(/<[^>]*[?&]page=(\d+)[^>]*>;\s*rel="last"/);
+    if (!lastMatch)
+        return null;
+    const lastResp = await fetch(`https://api.github.com/repos/${repo}/commits?per_page=1&page=${lastMatch[1]}`, {
+        headers,
+    });
+    if (!lastResp.ok)
+        return null;
+    const lastData = await lastResp.json();
+    const lastCommits = lastData;
+    return lastCommits[0]?.sha ?? null;
+}
+/** Resolves a commit SHA from a full 40-char SHA, branch name, or the repo's default branch. */
+export async function resolveCommitSha(target, token, repo) {
+    if (target && /^[0-9a-f]{40}$/i.test(target))
+        return target;
+    let branchName = target;
+    if (!branchName) {
+        const repoInfo = await gh(token, `/repos/${repo}`);
+        branchName = repoInfo.default_branch;
+    }
+    const branchInfo = await gh(token, `/repos/${repo}/branches/${branchName}`);
+    return branchInfo.commit.sha;
+}
+// ---- OAuth device flow -------------------------------------------------------
+const CLIENT_ID = 'Ov23liy9NAepXOSybR7K';
+const DEVICE_CODE_URL = 'https://github.com/login/device/code';
+const TOKEN_URL = 'https://github.com/login/oauth/access_token';
+const SCOPE = 'repo';
+/** Initiates the GitHub OAuth device flow and returns the device code response. */
+export async function requestDeviceCode() {
+    const resp = await fetch(DEVICE_CODE_URL, {
+        method: 'POST',
+        headers: { Accept: 'application/json', 'Content-Type': 'application/json' },
+        body: JSON.stringify({ client_id: CLIENT_ID, scope: SCOPE }),
+    });
+    return resp.json();
+}
+/** Polls the GitHub token endpoint until the user authorizes the device or an error occurs. */
+export async function pollForToken(deviceCode, interval) {
+    await new Promise((res) => setTimeout(res, interval));
+    const resp = await fetch(TOKEN_URL, {
+        method: 'POST',
+        headers: { Accept: 'application/json', 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+            client_id: CLIENT_ID,
+            device_code: deviceCode,
+            grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+        }),
+    });
+    const data = (await resp.json());
+    if (data.access_token)
+        return data.access_token;
+    // c8 ignore next — slow_down retry delay is always ≥5 s; testing would block the suite
+    if (data.error === 'slow_down')
+        return pollForToken(deviceCode, ((data.interval ?? interval) / 1000 + 5) * 1000);
+    if (data.error === 'authorization_pending')
+        return pollForToken(deviceCode, interval);
+    throw new ExpectedError(`GitHub authorization failed: ${data.error ?? 'unknown error'}`);
+}
+//# sourceMappingURL=service.github.js.map

package/lib/core/service.github.js.map

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

package/lib/core/service.js

@@ -0,0 +1,91 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { Entry } from '@napi-rs/keyring';
+import { ensureDir, listDir, readJson, writeJson, removeFile } from './file.js';
+const KEYRING_SERVICE = 'plugin-ship';
+/** Returns the path to the plugin-ship services directory, creating it if needed. */
+function getServicesDir() {
+    const dir = join(homedir(), '.sf', 'plugin-ship', 'services');
+    ensureDir(dir);
+    return dir;
+}
+function metaFilePath(service, account, alias) {
+    return join(getServicesDir(), `${service}-${account}-${alias}.meta.json`);
+}
+/**
+ * Retrieves the stored token for a service alias from the OS keychain.
+ *
+ * @param service - The external service name (e.g. `'github.com'`).
+ * @param alias - The account alias (e.g. `'default'`).
+ * @returns The stored token, or `null` if not found.
+ */
+export function getToken(service, alias) {
+    return new Entry(KEYRING_SERVICE, `${service}:${alias}`).getPassword() ?? null;
+}
+/**
+ * Stores a token in the OS keychain and writes a metadata file alongside it.
+ *
+ * @param service - The external service name (e.g. `'github.com'`).
+ * @param account - The account identifier (e.g. GitHub username).
+ * @param alias - The account alias (e.g. `'default'`).
+ * @param token - The credential to store.
+ * @param scopes - The scopes or permissions granted to this credential.
+ */
+export function setToken(service, account, alias, token, scopes = []) {
+    new Entry(KEYRING_SERVICE, `${service}:${alias}`).setPassword(token);
+    writeJson(metaFilePath(service, account, alias), { service, account, alias, scopes });
+}
+/**
+ * Reads the metadata for a stored credential by alias.
+ *
+ * @param service - The external service name.
+ * @param alias - The account alias to look up.
+ * @returns The metadata, or `undefined` if no credential is stored for this alias.
+ */
+export function getMeta(service, alias) {
+    const dir = getServicesDir();
+    const file = listDir(dir).find((f) => f.startsWith(`${service}-`) && f.endsWith(`-${alias}.meta.json`));
+    if (!file)
+        return undefined;
+    return readJson(join(dir, file));
+}
+/**
+ * Returns metadata for all stored credentials.
+ */
+export function listMetas() {
+    const dir = getServicesDir();
+    return listDir(dir)
+        .filter((f) => f.endsWith('.meta.json'))
+        .map((f) => readJson(join(dir, f)));
+}
+/**
+ * Removes a stored credential from the OS keychain and deletes its metadata file.
+ *
+ * @param service - The external service name.
+ * @param account - The account identifier.
+ * @param alias - The account alias.
+ */
+export function deleteToken(service, account, alias) {
+    new Entry(KEYRING_SERVICE, `${service}:${alias}`).deletePassword();
+    try {
+        removeFile(metaFilePath(service, account, alias));
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT')
+            throw err;
+    }
+}
+//# sourceMappingURL=service.js.map

package/lib/core/service.js.map

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

package/lib/core/sfdx-project.d.ts

@@ -0,0 +1,25 @@
+/** A single `packageDirectories` entry. Only the fields ship reads or writes are typed. */
+export type PackageDirectory = {
+    [key: string]: unknown;
+    path: string;
+    package?: string;
+    default?: boolean;
+    dependencies?: Array<{
+        package: string;
+        versionNumber?: string;
+    }>;
+};
+/** The parsed shape of `sfdx-project.json`. Unmodeled fields are preserved on write. */
+export type SfdxProject = {
+    [key: string]: unknown;
+    packageDirectories: PackageDirectory[];
+    packageAliases?: Record<string, string>;
+};
+/** Reads and parses `sfdx-project.json` from the project directory. */
+export declare function readSfdxProject(projectDir: string): SfdxProject;
+/** Writes `sfdx-project.json` back, preserving 2-space indentation and a trailing newline. */
+export declare function writeSfdxProject(projectDir: string, project: SfdxProject): void;
+/** Returns the default packageDirectory (the one flagged `default`, else the first), or undefined if none exist. */
+export declare function defaultPackageDirectory(project: SfdxProject): PackageDirectory | undefined;
+/** Reads sfdx-project.json and returns the package alias of the default packageDirectory. Returns null on any error. */
+export declare function defaultPackageAlias(projectDir: string): string | null;

package/lib/core/sfdx-project.js

@@ -0,0 +1,39 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { join } from 'node:path';
+import { readJson, writeJson } from './file.js';
+const FILE = 'sfdx-project.json';
+/** Reads and parses `sfdx-project.json` from the project directory. */
+export function readSfdxProject(projectDir) {
+    return readJson(join(projectDir, FILE));
+}
+/** Writes `sfdx-project.json` back, preserving 2-space indentation and a trailing newline. */
+export function writeSfdxProject(projectDir, project) {
+    writeJson(join(projectDir, FILE), project);
+}
+/** Returns the default packageDirectory (the one flagged `default`, else the first), or undefined if none exist. */
+export function defaultPackageDirectory(project) {
+    return project.packageDirectories?.find((d) => d.default) ?? project.packageDirectories?.[0];
+}
+/** Reads sfdx-project.json and returns the package alias of the default packageDirectory. Returns null on any error. */
+export function defaultPackageAlias(projectDir) {
+    try {
+        const project = readSfdxProject(projectDir);
+        return defaultPackageDirectory(project)?.package ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=sfdx-project.js.map

package/lib/core/sfdx-project.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sfdx-project.js","sourceRoot":"","sources":["../../src/core/sfdx-project.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAkBhD,MAAM,IAAI,GAAG,mBAAmB,CAAC;AAEjC,uEAAuE;AACvE,MAAM,UAAU,eAAe,CAAC,UAAkB;IAChD,OAAO,QAAQ,CAAc,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC,CAAC;AACvD,CAAC;AAED,8FAA8F;AAC9F,MAAM,UAAU,gBAAgB,CAAC,UAAkB,EAAE,OAAoB;IACvE,SAAS,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,EAAE,OAAO,CAAC,CAAC;AAC7C,CAAC;AAED,oHAAoH;AACpH,MAAM,UAAU,uBAAuB,CAAC,OAAoB;IAC1D,OAAO,OAAO,CAAC,kBAAkB,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAAC,CAAC,CAAC;AAC/F,CAAC;AAED,wHAAwH;AACxH,MAAM,UAAU,mBAAmB,CAAC,UAAkB;IACpD,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,eAAe,CAAC,UAAU,CAAC,CAAC;QAC5C,OAAO,uBAAuB,CAAC,OAAO,CAAC,EAAE,OAAO,IAAI,IAAI,CAAC;IAC3D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/lib/core/stdout.d.ts

@@ -0,0 +1 @@
+export declare function withSuppressedStdout<T>(fn: () => Promise<T>): Promise<T>;

package/lib/core/stdout.js

@@ -0,0 +1,27 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+export async function withSuppressedStdout(fn) {
+    const originalOut = process.stdout.write.bind(process.stdout);
+    const originalErr = process.stderr.write.bind(process.stderr);
+    process.stdout.write = () => true;
+    process.stderr.write = () => true;
+    try {
+        return await fn();
+    }
+    finally {
+        process.stdout.write = originalOut;
+        process.stderr.write = originalErr;
+    }
+}
+//# sourceMappingURL=stdout.js.map

package/lib/core/stdout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdout.js","sourceRoot":"","sources":["../../src/core/stdout.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAI,EAAoB;IAChE,MAAM,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAC9D,MAAM,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAC9D,OAAO,CAAC,MAAM,CAAC,KAAK,GAAG,GAAY,EAAE,CAAC,IAAI,CAAC;IAC3C,OAAO,CAAC,MAAM,CAAC,KAAK,GAAG,GAAY,EAAE,CAAC,IAAI,CAAC;IAC3C,IAAI,CAAC;QACH,OAAO,MAAM,EAAE,EAAE,CAAC;IACpB,CAAC;YAAS,CAAC;QACT,OAAO,CAAC,MAAM,CAAC,KAAK,GAAG,WAAW,CAAC;QACnC,OAAO,CAAC,MAAM,CAAC,KAAK,GAAG,WAAW,CAAC;IACrC,CAAC;AACH,CAAC"}

package/lib/core/task.definition.schema.d.ts

@@ -0,0 +1,69 @@
+import { z } from 'zod';
+import { Params } from './task.param.schema.js';
+import { FlowContext } from './flow.context.js';
+import { TaskOutput } from './task.output.js';
+/** Zod schema for a value this task writes to the flow outputs. */
+export declare const TaskOutputDefinitionSchema: z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodEnum<{
+        string: "string";
+        number: "number";
+        boolean: "boolean";
+        object: "object";
+    }>;
+    description: z.ZodString;
+}, z.core.$strip>;
+/** Describes a value this task writes to the flow outputs. */
+export type TaskOutputDefinition = z.infer<typeof TaskOutputDefinitionSchema>;
+/**
+ * The runtime context passed to a task's `run()` method.
+ * Combines the broader flow context with the task's resolved, validated params.
+ */
+export type TaskContext = {
+    /** The parent flow's context, including config, org registry, and logger. */
+    flow: FlowContext;
+    /** The validated params for this task invocation. */
+    params: Params;
+    /** Reads and writes named output values for this step. */
+    output: TaskOutput;
+};
+/**
+ * The shape every task must satisfy — built-in or custom.
+ * Custom tasks are duck-typed against this at runtime.
+ */
+export declare const TaskSchema: z.ZodObject<{
+    description: z.ZodDefault<z.ZodString>;
+    params: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        type: z.ZodDefault<z.ZodEnum<{
+            string: "string";
+            number: "number";
+            boolean: "boolean";
+            record: "record";
+        }>>;
+        required: z.ZodOptional<z.ZodBoolean>;
+        default: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    outputs: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        type: z.ZodEnum<{
+            string: "string";
+            number: "number";
+            boolean: "boolean";
+            object: "object";
+        }>;
+        description: z.ZodString;
+    }, z.core.$strip>>>;
+    run: z.ZodFunction<z.core.$ZodFunctionArgs, z.core.$ZodFunctionOut>;
+}, z.core.$strip>;
+/** The input shape a task file must export — fields with defaults are optional. */
+export type TaskDefinition = z.input<typeof TaskSchema>;
+/**
+ * A fully loaded task, with all fields normalized and `name` injected from the file path.
+ * This is the type the runner works with internally after loading a {@link TaskDefinition}.
+ */
+export type Task = Omit<z.infer<typeof TaskSchema>, 'run'> & {
+    name: string;
+    run: (context: TaskContext) => Promise<void>;
+};

package/lib/core/task.definition.schema.js

@@ -0,0 +1,33 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { z } from 'zod';
+import { ParamDefinitionSchema } from './task.param.schema.js';
+/** Zod schema for a value this task writes to the flow outputs. */
+export const TaskOutputDefinitionSchema = z.object({
+    name: z.string(),
+    type: z.enum(['string', 'number', 'boolean', 'object']),
+    description: z.string(),
+});
+/**
+ * The shape every task must satisfy — built-in or custom.
+ * Custom tasks are duck-typed against this at runtime.
+ */
+export const TaskSchema = z.object({
+    description: z.string().default(''),
+    params: z.array(ParamDefinitionSchema).default([]),
+    outputs: z.array(TaskOutputDefinitionSchema).default([]),
+    run: z.function(),
+});
+/* c8 ignore stop */
+//# sourceMappingURL=task.definition.schema.js.map

package/lib/core/task.definition.schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"task.definition.schema.js","sourceRoot":"","sources":["../../src/core/task.definition.schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,qBAAqB,EAAU,MAAM,wBAAwB,CAAC;AAIvE,mEAAmE;AACnE,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,CAAC,MAAM,CAAC;IACjD,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;IACvD,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;CACxB,CAAC,CAAC;AAkBH;;;GAGG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAC,MAAM,CAAC;IACjC,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC;IACnC,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,qBAAqB,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;IAClD,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,0BAA0B,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;IACxD,GAAG,EAAE,CAAC,CAAC,QAAQ,EAAE;CAClB,CAAC,CAAC;AAaH,oBAAoB"}

package/lib/core/task.output.d.ts

@@ -0,0 +1,29 @@
+import type { Store } from './flow.store.js';
+/**
+ * Task-facing output API. Passed into `TaskContext` so tasks can read and write
+ * step outputs without holding a reference to the full `Store`.
+ *
+ * - `get(key)` — reads this step's own output.
+ * - `get(stepId, key)` — reads another step's output by its ID.
+ * - `set(key, value)` — writes a named output value under this step's namespace.
+ */
+export declare class TaskOutput {
+    private readonly stepId;
+    private readonly store;
+    constructor(stepId: string, store: Store);
+    /**
+     * Writes a named output value under this step's namespace,
+     * making it available to subsequent steps via `${{ steps.<id>.<key> }}`.
+     *
+     * @param key - The output key.
+     * @param value - The value to store.
+     */
+    set(key: string, value: unknown): void;
+    /**
+     * Reads an output value.
+     *
+     * @param keyOrStepId - The output key (own step) or step ID (other step).
+     * @param key - The output key when reading from another step.
+     */
+    get(keyOrStepId: string, key?: string): unknown;
+}