@synopackageland/cli 0.1.0

package/dist/publish/file-build-ledger.d.ts

@@ -0,0 +1,18 @@
+import type { BuildLedger, BuildLedgerSnapshot } from "./build-ledger.js";
+export declare const BUILD_LEDGER_FILENAME = "package-build-ledger.jsonl";
+export declare const BUILD_LEDGER_PATH_ENV = "SYNOPKGLAND_BUILD_LEDGER_PATH";
+export interface ResolveBuildLedgerPathOptions {
+    env?: NodeJS.Dict<string>;
+    cwd?: string;
+    communityAppsRoot?: string;
+}
+export declare function defaultBuildLedgerPath(communityAppsRoot: string): string;
+export declare function resolveBuildLedgerPath(options?: ResolveBuildLedgerPathOptions): string;
+export declare class FileBuildLedger implements BuildLedger {
+    readonly ledgerPath: string;
+    constructor(ledgerPath: string);
+    allocate(packageIdentity: string): number;
+    markPublishFailed(packageIdentity: string, build: number): void;
+    snapshot(packageIdentity: string): BuildLedgerSnapshot;
+}
+export declare function runFileBuildLedgerCli(argv: string[], env?: NodeJS.Dict<string>): void;

package/dist/publish/file-build-ledger.js

@@ -0,0 +1,268 @@
+/**
+ * Durable append-only Package Build ledger for protected-main merge CI.
+ *
+ * Default path: synopkgland-community-apps/ci/package-build-ledger.jsonl
+ * (override with SYNOPKGLAND_BUILD_LEDGER_PATH). Concurrent allocate() is
+ * serialized with an exclusive lockfile next to the ledger. Do not commit live
+ * numbers; Git history / release artifacts remain disaster recovery.
+ *
+ * This module does not sign, upload artifacts, or mutate Package Source index.
+ */
+import { randomUUID } from "node:crypto";
+import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, statSync, unlinkSync, writeSync, } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { resolveCommunityAppsRoot } from "./community-path.js";
+export const BUILD_LEDGER_FILENAME = "package-build-ledger.jsonl";
+export const BUILD_LEDGER_PATH_ENV = "SYNOPKGLAND_BUILD_LEDGER_PATH";
+const LOCK_RETRY_MS = 15;
+const LOCK_TIMEOUT_MS = 30_000;
+const LOCK_FRESH_MS = 2_000;
+export function defaultBuildLedgerPath(communityAppsRoot) {
+    return join(communityAppsRoot, "ci", BUILD_LEDGER_FILENAME);
+}
+export function resolveBuildLedgerPath(options = {}) {
+    const env = options.env ?? process.env;
+    const fromEnv = env[BUILD_LEDGER_PATH_ENV]?.trim();
+    if (fromEnv) {
+        return resolve(fromEnv);
+    }
+    const cwd = options.cwd ?? process.cwd();
+    const communityRoot = options.communityAppsRoot ?? resolveCommunityAppsRoot(cwd);
+    if (communityRoot) {
+        return defaultBuildLedgerPath(communityRoot);
+    }
+    return resolve(cwd, "synopkgland-community-apps", "ci", BUILD_LEDGER_FILENAME);
+}
+export class FileBuildLedger {
+    ledgerPath;
+    constructor(ledgerPath) {
+        this.ledgerPath = ledgerPath;
+    }
+    allocate(packageIdentity) {
+        requirePackageIdentity(packageIdentity);
+        return withLedgerLock(this.ledgerPath, () => {
+            const records = readRecords(this.ledgerPath);
+            const build = lastAllocated(records, packageIdentity) + 1;
+            appendRecord(this.ledgerPath, {
+                packageIdentity,
+                build,
+                event: "allocated",
+                at: new Date().toISOString(),
+            });
+            return build;
+        });
+    }
+    markPublishFailed(packageIdentity, build) {
+        requirePackageIdentity(packageIdentity);
+        withLedgerLock(this.ledgerPath, () => {
+            appendRecord(this.ledgerPath, {
+                packageIdentity,
+                build,
+                event: "publish-failed",
+                at: new Date().toISOString(),
+            });
+        });
+    }
+    snapshot(packageIdentity) {
+        requirePackageIdentity(packageIdentity);
+        return withLedgerLock(this.ledgerPath, () => snapshotFromRecords(readRecords(this.ledgerPath), packageIdentity));
+    }
+}
+export function runFileBuildLedgerCli(argv, env = process.env) {
+    const command = argv[2];
+    const ledger = new FileBuildLedger(resolveBuildLedgerPath({ env }));
+    if (command === "allocate") {
+        const packageIdentity = requirePackageIdentity(argv[3]);
+        const build = ledger.allocate(packageIdentity);
+        process.stdout.write(`${JSON.stringify({ packageIdentity, build })}\n`);
+        return;
+    }
+    if (command === "mark-failed") {
+        const packageIdentity = requirePackageIdentity(argv[3]);
+        const build = Number(argv[4]);
+        if (!Number.isInteger(build) || build < 1) {
+            throw new Error("usage: file-build-ledger mark-failed <packageIdentity> <build>");
+        }
+        ledger.markPublishFailed(packageIdentity, build);
+        process.stdout.write(`${JSON.stringify({ packageIdentity, build, event: "publish-failed" })}\n`);
+        return;
+    }
+    if (command === "snapshot") {
+        const packageIdentity = requirePackageIdentity(argv[3]);
+        process.stdout.write(`${JSON.stringify({ packageIdentity, ...ledger.snapshot(packageIdentity) })}\n`);
+        return;
+    }
+    throw new Error("usage: file-build-ledger <allocate|mark-failed|snapshot> <packageIdentity> [build]");
+}
+function requirePackageIdentity(packageIdentity) {
+    if (typeof packageIdentity !== "string" || packageIdentity.trim().length === 0) {
+        throw new Error("package identity is required");
+    }
+    return packageIdentity;
+}
+function snapshotFromRecords(records, packageIdentity) {
+    const consumed = records
+        .filter((record) => record.packageIdentity === packageIdentity && record.event === "allocated")
+        .map((record) => record.build);
+    return {
+        nextBuild: lastAllocated(records, packageIdentity),
+        consumed,
+    };
+}
+function lastAllocated(records, packageIdentity) {
+    let max = 0;
+    for (const record of records) {
+        if (record.packageIdentity === packageIdentity && record.event === "allocated" && record.build > max) {
+            max = record.build;
+        }
+    }
+    return max;
+}
+function readRecords(ledgerPath) {
+    if (!existsSync(ledgerPath)) {
+        return [];
+    }
+    const text = readFileSync(ledgerPath, "utf8");
+    const records = [];
+    for (const [index, line] of text.split("\n").entries()) {
+        if (line.trim().length === 0) {
+            continue;
+        }
+        try {
+            records.push(JSON.parse(line));
+        }
+        catch (error) {
+            throw new Error(`invalid ledger record at ${ledgerPath}:${index + 1}: ${String(error)}`);
+        }
+    }
+    return records;
+}
+function appendRecord(ledgerPath, record) {
+    mkdirSync(dirname(ledgerPath), { recursive: true });
+    const fd = openSync(ledgerPath, "a");
+    try {
+        writeSync(fd, `${JSON.stringify(record)}\n`);
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function withLedgerLock(ledgerPath, fn) {
+    const lockPath = `${ledgerPath}.lock`;
+    mkdirSync(dirname(ledgerPath), { recursive: true });
+    const held = acquireExclusiveLock(lockPath);
+    try {
+        return fn();
+    }
+    finally {
+        releaseLock(held.fd, lockPath, held.token);
+    }
+}
+function acquireExclusiveLock(lockPath) {
+    const started = Date.now();
+    for (;;) {
+        const token = randomUUID();
+        try {
+            const fd = openSync(lockPath, "wx");
+            writeSync(fd, `${process.pid} ${token}\n`);
+            fsyncSync(fd);
+            return { fd, token };
+        }
+        catch (error) {
+            if (!isAlreadyExists(error)) {
+                throw error;
+            }
+            if (Date.now() - started > LOCK_TIMEOUT_MS) {
+                throw new Error(`timed out acquiring ledger lock: ${lockPath}`);
+            }
+            stealIfStale(lockPath);
+            sleepSync(LOCK_RETRY_MS);
+        }
+    }
+}
+function stealIfStale(lockPath) {
+    try {
+        const ageMs = Date.now() - statSync(lockPath).mtimeMs;
+        if (ageMs < LOCK_FRESH_MS) {
+            return;
+        }
+        const parsed = parseLockOwner(readFileSync(lockPath, "utf8"));
+        if (parsed && pidIsAlive(parsed.pid) && ageMs < LOCK_TIMEOUT_MS) {
+            return;
+        }
+        unlinkSync(lockPath);
+    }
+    catch (error) {
+        if (!isNotFound(error)) {
+            return;
+        }
+    }
+}
+function parseLockOwner(raw) {
+    const match = raw.trim().match(/^(\d+)\s+(\S+)$/);
+    if (!match) {
+        return null;
+    }
+    const pid = Number(match[1]);
+    if (!Number.isInteger(pid) || pid <= 0) {
+        return null;
+    }
+    return { pid, token: match[2] };
+}
+function releaseLock(fd, lockPath, token) {
+    try {
+        closeSync(fd);
+    }
+    finally {
+        try {
+            const parsed = parseLockOwner(readFileSync(lockPath, "utf8"));
+            if (parsed?.token === token) {
+                unlinkSync(lockPath);
+            }
+        }
+        catch {
+            // Best effort; a leftover lock is stolen if the holder is gone.
+        }
+    }
+}
+function pidIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+function isAlreadyExists(error) {
+    return typeof error === "object" && error !== null && "code" in error && error.code === "EEXIST";
+}
+function isNotFound(error) {
+    return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+function invokedAsCli() {
+    const entry = process.argv[1];
+    if (!entry) {
+        return false;
+    }
+    try {
+        return resolve(fileURLToPath(import.meta.url)) === resolve(entry);
+    }
+    catch {
+        return pathToFileURL(resolve(entry)).href === import.meta.url;
+    }
+}
+if (invokedAsCli()) {
+    try {
+        runFileBuildLedgerCli(process.argv);
+    }
+    catch (error) {
+        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        process.exit(1);
+    }
+}

package/dist/publish/github-pr.d.ts

@@ -0,0 +1,25 @@
+export interface CreatePullRequestOptions {
+    title: string;
+    body: string;
+    base: string;
+    head: string;
+    draft?: boolean;
+}
+export interface PullRequestRef {
+    url: string;
+    number: number;
+}
+export interface GitHubCli {
+    createPullRequest(options: CreatePullRequestOptions): Promise<PullRequestRef>;
+}
+export interface GitOps {
+    currentBranch(): string;
+    checkoutNewBranch(branchName: string): void;
+    checkoutExisting(branchName: string): void;
+    add(paths: string[]): void;
+    commit(message: string, paths: string[]): void;
+    push(branchName: string, setUpstream: boolean): void;
+    hasChanges(paths: string[]): boolean;
+}
+export declare function createExecGitOps(cwd: string): GitOps;
+export declare function createExecGitHubCli(cwd: string, repo?: string): GitHubCli;

package/dist/publish/github-pr.js

@@ -0,0 +1,85 @@
+import { execFileSync } from "node:child_process";
+import { communityAppsGitHubRepo, githubToken } from "./github-repo.js";
+export function createExecGitOps(cwd) {
+    const run = (args) => execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+    return {
+        currentBranch() {
+            return run(["rev-parse", "--abbrev-ref", "HEAD"]);
+        },
+        checkoutNewBranch(branchName) {
+            run(["checkout", "-b", branchName]);
+        },
+        checkoutExisting(branchName) {
+            run(["checkout", branchName]);
+        },
+        add(paths) {
+            if (paths.length === 0) {
+                return;
+            }
+            run(["add", "--", ...paths]);
+        },
+        commit(message, paths) {
+            if (paths.length === 0) {
+                throw new Error("git commit requires a pathspec");
+            }
+            run(["commit", "-m", message, "--", ...paths]);
+        },
+        push(branchName, setUpstream) {
+            const args = ["push"];
+            if (setUpstream) {
+                args.push("-u", "origin", branchName);
+            }
+            else {
+                args.push("origin", branchName);
+            }
+            run(args);
+        },
+        hasChanges(paths) {
+            if (paths.length === 0) {
+                return false;
+            }
+            const status = run(["status", "--porcelain", "--", ...paths]);
+            return status.length > 0;
+        },
+    };
+}
+export function createExecGitHubCli(cwd, repo) {
+    const targetRepo = repo ?? communityAppsGitHubRepo();
+    return {
+        async createPullRequest(options) {
+            const token = githubToken();
+            const args = [
+                "pr",
+                "create",
+                "--repo",
+                targetRepo,
+                "--title",
+                options.title,
+                "--body",
+                options.body,
+                "--base",
+                options.base,
+                "--head",
+                options.head,
+            ];
+            if (options.draft) {
+                args.push("--draft");
+            }
+            const stdout = execFileSync("gh", args, {
+                cwd,
+                encoding: "utf8",
+                stdio: ["ignore", "pipe", "pipe"],
+                env: {
+                    ...process.env,
+                    ...(token ? { GH_TOKEN: token, GITHUB_TOKEN: token } : {}),
+                },
+            }).trim();
+            const url = stdout.split(/\s+/).pop() ?? stdout;
+            const match = url.match(/\/pull\/(\d+)\/?$/);
+            return {
+                url,
+                number: match ? Number(match[1]) : 0,
+            };
+        },
+    };
+}

package/dist/publish/github-repo.d.ts

@@ -0,0 +1,8 @@
+export declare const DEFAULT_GITHUB_OWNER = "synopackageland";
+export declare const COMMUNITY_APPS_GITHUB_REPO = "synopkgland-community-apps";
+export declare const PLATFORM_GITHUB_REPO = "syno-package-land";
+export declare function githubOwner(env?: NodeJS.ProcessEnv): string;
+export declare function communityAppsGitHubRepo(env?: NodeJS.ProcessEnv): string;
+export declare function communityAppsGitHubUrl(env?: NodeJS.ProcessEnv): string;
+export declare function platformGitHubUrl(env?: NodeJS.ProcessEnv): string;
+export declare function githubToken(env?: NodeJS.ProcessEnv): string | undefined;

package/dist/publish/github-repo.js

@@ -0,0 +1,21 @@
+export const DEFAULT_GITHUB_OWNER = "synopackageland";
+export const COMMUNITY_APPS_GITHUB_REPO = "synopkgland-community-apps";
+export const PLATFORM_GITHUB_REPO = "syno-package-land";
+export function githubOwner(env = process.env) {
+    const fromEnv = env.GITHUB_OWNER?.trim();
+    return fromEnv && fromEnv.length > 0 ? fromEnv : DEFAULT_GITHUB_OWNER;
+}
+export function communityAppsGitHubRepo(env = process.env) {
+    const repo = env.GITHUB_COMMUNITY_APPS_REPO?.trim() || COMMUNITY_APPS_GITHUB_REPO;
+    return `${githubOwner(env)}/${repo}`;
+}
+export function communityAppsGitHubUrl(env = process.env) {
+    return `https://github.com/${communityAppsGitHubRepo(env)}`;
+}
+export function platformGitHubUrl(env = process.env) {
+    return `https://github.com/${githubOwner(env)}/${PLATFORM_GITHUB_REPO}`;
+}
+export function githubToken(env = process.env) {
+    const token = env.GH_TOKEN?.trim() || env.GITHUB_TOKEN?.trim();
+    return token && token.length > 0 ? token : undefined;
+}

package/dist/publish/publish.d.ts

@@ -0,0 +1,23 @@
+import type { ProjectRoot } from "../discovery.js";
+import type { GitHubCli, GitOps } from "./github-pr.js";
+export interface PublishProjectOptions {
+    project: ProjectRoot;
+    communityAppsRoot?: string;
+    baseBranch?: string;
+    branchPrefix?: string;
+    github: GitHubCli;
+    git: GitOps;
+    now?: () => Date;
+}
+export interface PublishProjectResult {
+    ok: boolean;
+    code?: string;
+    message?: string;
+    packageIdentity?: string;
+    prUrl?: string;
+    prNumber?: number;
+    branchName?: string;
+    noChanges?: boolean;
+}
+export declare function publishProject(options: PublishProjectOptions): Promise<PublishProjectResult>;
+export { resolveCommunityAppsRoot, communityAppDirectory, listCommunityAppDirectories } from "./community-path.js";

package/dist/publish/publish.js

@@ -0,0 +1,128 @@
+import { join, resolve } from "node:path";
+import { loadContract } from "../contract/load.js";
+import { validateProject } from "../validate.js";
+import { assertDirectoryMatchesPackage, COMMUNITY_APPS_APPS_DIR, COMMUNITY_APPS_DIR, communityAppDirectory, resolveCommunityAppsRoot, } from "./community-path.js";
+import { listSyncedRelativePaths, syncPackagingDefinition } from "./sync-definition.js";
+function slugifyPackageIdentity(packageIdentity) {
+    return packageIdentity.replace(/[^a-zA-Z0-9._-]+/g, "-");
+}
+function renderPullRequestBody(packageIdentity, appRelativePath, files) {
+    return [
+        "## Summary",
+        "",
+        `Publish Packaging Definition for \`${packageIdentity}\`.`,
+        "",
+        "## Checklist",
+        "",
+        "- [ ] 變更摘要",
+        "- [ ] Image 來源（公開 registry／digest）",
+        "- [ ] 是否新增 User File Scope 或 secret",
+        "",
+        "## Synced paths",
+        "",
+        `\`${appRelativePath}/\``,
+        "",
+        files.map((file) => `- \`${file}\``).join("\n"),
+        "",
+        "_Opened by `synopkgland publish`. PR CI runs validate + preview only; no signing or Package Build allocation._",
+    ].join("\n");
+}
+export async function publishProject(options) {
+    const validation = validateProject(options.project, { profile: "listing" });
+    if (!validation.ok) {
+        return {
+            ok: false,
+            code: "VALIDATION_FAILED",
+            message: validation.errors.map((error) => error.code).join(", "),
+        };
+    }
+    const communityRoot = options.communityAppsRoot ?? resolveCommunityAppsRoot(options.project.root);
+    if (!communityRoot) {
+        return {
+            ok: false,
+            code: "COMMUNITY_APPS_ROOT_MISSING",
+            message: "找不到 synopkgland-community-apps/apps。請在 monorepo 根目錄執行，或設定 SYNOPKGLAND_COMMUNITY_APPS_ROOT。",
+        };
+    }
+    const contract = loadContract(options.project.contractPath).contract;
+    const packageIdentity = contract.package;
+    if (typeof packageIdentity !== "string" || packageIdentity.length === 0) {
+        return {
+            ok: false,
+            code: "PACKAGE_IDENTITY_MISSING",
+            message: "App Contract 缺少有效的 package 欄位。",
+        };
+    }
+    const targetDir = communityAppDirectory(communityRoot, packageIdentity);
+    try {
+        assertDirectoryMatchesPackage(packageIdentity, targetDir);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            code: "PACKAGE_DIRECTORY_MISMATCH",
+            message: error instanceof Error ? error.message : String(error),
+        };
+    }
+    if (resolve(options.project.root) === resolve(targetDir)) {
+        return {
+            ok: false,
+            code: "PUBLISH_SOURCE_IS_COMMUNITY_APP",
+            message: "publish 的專案根目錄不能是 Community Apps 目標目錄。請對開發專案執行，不要對 synopkgland-community-apps/apps/<package> 本身執行。",
+            packageIdentity,
+        };
+    }
+    syncPackagingDefinition(options.project, targetDir);
+    const appRelativePath = join(COMMUNITY_APPS_DIR, COMMUNITY_APPS_APPS_DIR, packageIdentity);
+    const syncedFiles = listSyncedRelativePaths(targetDir);
+    const baseBranch = options.baseBranch ?? "master";
+    const branchPrefix = options.branchPrefix ?? "publish";
+    const stamp = (options.now ?? (() => new Date()))().toISOString().replace(/[:.]/g, "-");
+    const branchName = `${branchPrefix}/${slugifyPackageIdentity(packageIdentity)}-${stamp}`;
+    if (!options.git.hasChanges([appRelativePath])) {
+        return {
+            ok: true,
+            noChanges: true,
+            packageIdentity,
+            message: "Community Apps 定義已是最新，未建立 PR。",
+        };
+    }
+    const previousBranch = options.git.currentBranch();
+    try {
+        options.git.checkoutNewBranch(branchName);
+        options.git.add([appRelativePath]);
+        options.git.commit(`Publish ${packageIdentity} packaging definition`, [appRelativePath]);
+        options.git.push(branchName, true);
+        const pr = await options.github.createPullRequest({
+            title: `Publish ${packageIdentity}`,
+            body: renderPullRequestBody(packageIdentity, appRelativePath, syncedFiles),
+            base: baseBranch,
+            head: branchName,
+        });
+        return {
+            ok: true,
+            packageIdentity,
+            prUrl: pr.url,
+            prNumber: pr.number,
+            branchName,
+        };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            code: "PUBLISH_PR_FAILED",
+            message: error instanceof Error ? error.message : String(error),
+            packageIdentity,
+            branchName,
+        };
+    }
+    finally {
+        try {
+            options.git.checkoutExisting(previousBranch);
+        }
+        catch {
+            // Best effort restore; caller may be in a temp repo during tests.
+        }
+    }
+}
+export { resolveCommunityAppsRoot, communityAppDirectory, listCommunityAppDirectories } from "./community-path.js";

package/dist/publish/sync-definition.d.ts

@@ -0,0 +1,4 @@
+import type { ProjectRoot } from "../discovery.js";
+export declare function assertDistinctSyncPaths(sourceRoot: string, targetDir: string): void;
+export declare function syncPackagingDefinition(source: ProjectRoot, targetDir: string): void;
+export declare function listSyncedRelativePaths(targetDir: string): string[];

package/dist/publish/sync-definition.js

@@ -0,0 +1,48 @@
+import { cpSync, existsSync, mkdirSync, readdirSync, rmSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+const PACKAGING_DEFINITION_FILES = new Set(["synology-app.yaml", "compose.yaml", "README.md", "icon.png"]);
+const PACKAGING_DEFINITION_DIRS = new Set(["html"]);
+export function assertDistinctSyncPaths(sourceRoot, targetDir) {
+    if (resolve(sourceRoot) === resolve(targetDir)) {
+        throw new Error("publish 的專案根目錄不能是 Community Apps 目標目錄。請對開發專案執行，不要對 synopkgland-community-apps/apps/<package> 本身執行。");
+    }
+}
+export function syncPackagingDefinition(source, targetDir) {
+    assertDistinctSyncPaths(source.root, targetDir);
+    if (existsSync(targetDir)) {
+        rmSync(targetDir, { recursive: true, force: true });
+    }
+    mkdirSync(targetDir, { recursive: true });
+    for (const name of PACKAGING_DEFINITION_FILES) {
+        const from = join(source.root, name);
+        if (existsSync(from) && statSync(from).isFile()) {
+            cpSync(from, join(targetDir, name));
+        }
+    }
+    for (const name of PACKAGING_DEFINITION_DIRS) {
+        const from = join(source.root, name);
+        if (existsSync(from) && statSync(from).isDirectory()) {
+            cpSync(from, join(targetDir, name), { recursive: true });
+        }
+    }
+}
+export function listSyncedRelativePaths(targetDir) {
+    const paths = [];
+    const walk = (current, prefix) => {
+        if (!existsSync(current)) {
+            return;
+        }
+        for (const entry of readdirSync(current, { withFileTypes: true })) {
+            const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+            const absolute = join(current, entry.name);
+            if (entry.isDirectory()) {
+                walk(absolute, rel);
+            }
+            else {
+                paths.push(rel);
+            }
+        }
+    };
+    walk(targetDir, "");
+    return paths.sort();
+}

package/dist/skill.d.ts

@@ -0,0 +1,10 @@
+export interface SkillEntry {
+    id: string;
+    file: string;
+    when: string;
+}
+export declare function resolveSkillsRoot(): string;
+export declare function listSkills(): SkillEntry[];
+export declare function skillPath(id: string): string;
+export declare function readSkill(id: string): string;
+export declare function formatSkillList(): string;