@synopackageland/cli 0.1.0

package/dist/build-spk/reproducible-archive.js

@@ -0,0 +1,34 @@
+import { readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import * as tar from "tar";
+/** Every archive this CLI writes uses the same timestamp so builds are byte-identical. */
+export const FIXED_MTIME = new Date(0);
+/** Relative paths of every file under `root`, depth-first and sorted for a stable archive order. */
+export function collectArchiveEntries(root) {
+    const entries = [];
+    const walk = (relativeDir) => {
+        const absoluteDir = relativeDir ? join(root, relativeDir) : root;
+        for (const entry of readdirSync(absoluteDir).sort()) {
+            const relativePath = relativeDir ? `${relativeDir}/${entry}` : entry;
+            const absolutePath = join(absoluteDir, entry);
+            if (statSync(absolutePath).isDirectory()) {
+                walk(relativePath);
+            }
+            else {
+                entries.push(relativePath);
+            }
+        }
+    };
+    walk("");
+    return entries.sort((a, b) => a.localeCompare(b));
+}
+/** Writes `sourceDir` to `outputPath` as a tar whose bytes depend only on the file contents. */
+export async function createReproducibleTar(sourceDir, outputPath, options = {}) {
+    await tar.c({
+        file: outputPath,
+        cwd: sourceDir,
+        gzip: options.gzip ?? false,
+        portable: true,
+        mtime: FIXED_MTIME,
+    }, collectArchiveEntries(sourceDir));
+}

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export declare function runCli(argv: string[]): Promise<void>;

package/dist/cli.js

@@ -0,0 +1,345 @@
+import { Command } from "commander";
+import { resolve, dirname } from "node:path";
+import { findProjectRoot } from "./discovery.js";
+import { formatErrors } from "./errors.js";
+import { formatInspectReport, inspectProject } from "./inspect.js";
+import { initFromTemplate, isTemplateName, listTemplates } from "./init.js";
+import { validateProject } from "./validate.js";
+import { runDev } from "./dev.js";
+import { testProject } from "./test-command.js";
+import { buildSpk } from "./build-spk/generator.js";
+import { deployProject } from "./deploy/deploy.js";
+import { createNasHost } from "./host/dsm-client.js";
+import { projectInfo, formatProjectInfo } from "./info.js";
+import { followProjectLogs } from "./log.js";
+import { testProjectOnHost } from "./test-host.js";
+import { formatSkillList, readSkill, resolveSkillsRoot } from "./skill.js";
+import { publishProject, resolveCommunityAppsRoot } from "./publish/publish.js";
+import { createExecGitHubCli, createExecGitOps } from "./publish/github-pr.js";
+import { communityAppsGitHubRepo } from "./publish/github-repo.js";
+function collectKvOption(value, previous, flag, example) {
+    const separator = value.indexOf("=");
+    if (separator <= 0) {
+        throw new Error(`${flag} 格式應為 SLOT=邏輯名，例如 ${example}`);
+    }
+    return {
+        ...(previous ?? {}),
+        [value.slice(0, separator)]: value.slice(separator + 1),
+    };
+}
+function collectShareOption(value, previous) {
+    return collectKvOption(value, previous, "--share", "--share MEDIA_SHARE=photos");
+}
+function collectRunAsOption(value, previous) {
+    return collectKvOption(value, previous, "--run-as", "--run-as RUN_AS=alice");
+}
+function resolveProject(cwd, project) {
+    const start = project ? resolve(cwd, project) : cwd;
+    const found = findProjectRoot(start);
+    if (!found) {
+        console.error("找不到 synology-app.yaml。請在專案根目錄執行，或使用 --project 指定。");
+        process.exit(1);
+    }
+    return found;
+}
+export async function runCli(argv) {
+    const program = new Command();
+    program
+        .name("synopkgland")
+        .description("Syno Package Land Developer Kit CLI")
+        .option("--project <dir>", "App 專案根目錄");
+    program
+        .command("validate")
+        .description("驗證 App Contract 與 Compose")
+        .option("--curated", "使用 Curated listing profile（未宣告 privilege 為紅燈）")
+        .action((options, command) => {
+        const global = command.parent?.opts() ?? {};
+        const project = resolveProject(process.cwd(), global.project);
+        const result = validateProject(project, {
+            profile: options.curated ? "listing" : "personal",
+        });
+        if (result.warnings && result.warnings.length > 0) {
+            console.error(formatErrors(result.warnings));
+        }
+        if (!result.ok) {
+            console.error(formatErrors(result.errors));
+            process.exit(1);
+        }
+        console.log("驗證通過。");
+    });
+    program
+        .command("inspect")
+        .description("檢視 Compose 意圖與 Web entry 提示")
+        .action((_options, command) => {
+        const global = command.parent?.opts() ?? {};
+        const project = resolveProject(process.cwd(), global.project);
+        const report = inspectProject(project);
+        console.log(formatInspectReport(report));
+    });
+    program
+        .command("init")
+        .description("從模板建立 App 專案")
+        .requiredOption("-t, --template <name>", `模板：${listTemplates().join(" | ")}`)
+        .argument("[dir]", "目標目錄", ".")
+        .action((dir, options, command) => {
+        const global = command.parent?.opts() ?? {};
+        if (global.project) {
+            console.error("--project 不適用於 init。");
+            process.exit(1);
+        }
+        if (!isTemplateName(options.template)) {
+            console.error(`未知模板：${options.template}`);
+            process.exit(1);
+        }
+        const targetDir = resolve(process.cwd(), dir);
+        initFromTemplate(options.template, targetDir);
+        console.log(`已建立 ${options.template} 專案於 ${targetDir}`);
+    });
+    program
+        .command("dev")
+        .description("啟動本機 mock Broker 與 Compose")
+        .option("--files-root <dir>", "將本機目錄對應為 NAS Logical Path")
+        .action(async (options, command) => {
+        const global = command.parent?.opts() ?? {};
+        const project = resolveProject(process.cwd(), global.project);
+        const validation = validateProject(project);
+        if (!validation.ok) {
+            console.error(formatErrors(validation.errors));
+            process.exit(1);
+        }
+        try {
+            const handle = await runDev({
+                project,
+                filesRoot: options.filesRoot,
+            });
+            console.log(`Mock Broker：${handle.brokerBaseUrl}`);
+            console.log(`Bootstrap：${handle.bootstrapPath}`);
+            console.log("Compose 已就緒。按 Ctrl+C 結束。");
+            const shutdown = async () => {
+                await handle.close();
+                process.exit(0);
+            };
+            process.on("SIGINT", shutdown);
+            process.on("SIGTERM", shutdown);
+            await new Promise(() => { });
+        }
+        catch (error) {
+            console.error(error instanceof Error ? error.message : String(error));
+            process.exit(1);
+        }
+    });
+    program
+        .command("test")
+        .description("驗證契約並等待 Compose 就緒")
+        .option("--host <name>", "在已部署的 NAS 上執行 Open smoke")
+        .option("--dev", "檢查 Development Package Identity（{package}.dev）")
+        .action(async (options, command) => {
+        const global = command.parent?.opts() ?? {};
+        const project = resolveProject(process.cwd(), global.project);
+        if (options.host) {
+            const host = createNasHost({ host: options.host });
+            if (!host) {
+                console.error("找不到 NAS 憑證。請設定 synoagentcli profile 或 DSM_URL／DSM_PASSWORD。");
+                process.exit(1);
+            }
+            try {
+                const result = await testProjectOnHost({ project, host, dev: options.dev });
+                if (!result.ok) {
+                    console.error(result.message ?? "測試失敗。");
+                    process.exit(1);
+                }
+                console.log("NAS smoke 測試通過。");
+            }
+            catch (error) {
+                console.error(error instanceof Error ? error.message : String(error));
+                process.exit(1);
+            }
+            return;
+        }
+        try {
+            const result = await testProject({ project });
+            if (!result.ok) {
+                console.error(`測試失敗：${result.errors.join(", ")}`);
+                process.exit(1);
+            }
+            console.log("測試通過。");
+        }
+        catch (error) {
+            console.error(error instanceof Error ? error.message : String(error));
+            process.exit(1);
+        }
+    });
+    program
+        .command("deploy")
+        .description("Inner Loop Deploy 到 NAS（產生 SPK、簽發 Local Attestation、安裝）")
+        .requiredOption("--host <name>", "synoagentcli profile 或 NAS 名稱")
+        .option("--dev", "部署到 Development Package Identity（{package}.dev）")
+        .option("--replace-curated", "危險：將既有 Curated App Package Attestation 降級為 Local Attestation")
+        .option("--share <slot=name>", "此 NAS 上的 Shared Folder 邏輯名（契約 shared_folder 槽，可重複）", collectShareOption)
+        .option("--run-as <slot=name>", "此 NAS 上的 DSM 使用者邏輯名（契約 dsm_user 槽）", collectRunAsOption)
+        .action(async (options, command) => {
+        const global = command.parent?.opts() ?? {};
+        const project = resolveProject(process.cwd(), global.project);
+        const host = createNasHost({ host: options.host });
+        if (!host) {
+            console.error("找不到 NAS 憑證。請設定 synoagentcli profile 或 DSM_URL／DSM_PASSWORD。");
+            process.exit(1);
+        }
+        try {
+            const result = await deployProject({
+                project,
+                host,
+                dev: options.dev,
+                replaceCurated: options.replaceCurated,
+                shareValues: options.share,
+                runAsValues: options.runAs,
+            });
+            if (!result.ok) {
+                console.error(`[${result.code ?? "DEPLOY_FAILED"}] ${result.message ?? "部署失敗。"}`);
+                process.exit(1);
+            }
+            console.log(`已部署 ${result.packageId}`);
+            if (result.openUrl) {
+                console.log(`Open URL：${result.openUrl}`);
+            }
+        }
+        catch (error) {
+            console.error(error instanceof Error ? error.message : String(error));
+            process.exit(1);
+        }
+    });
+    program
+        .command("info")
+        .description("顯示 NAS 上的 attestation、Open URL 與 readiness")
+        .requiredOption("--host <name>", "synoagentcli profile 或 NAS 名稱")
+        .option("--dev", "查詢 Development Package Identity")
+        .action(async (options, command) => {
+        const global = command.parent?.opts() ?? {};
+        const project = resolveProject(process.cwd(), global.project);
+        const host = createNasHost({ host: options.host });
+        if (!host) {
+            console.error("找不到 NAS 憑證。請設定 synoagentcli profile 或 DSM_URL／DSM_PASSWORD。");
+            process.exit(1);
+        }
+        try {
+            const info = await projectInfo({ project, host, dev: options.dev });
+            console.log(formatProjectInfo(info));
+        }
+        catch (error) {
+            console.error(error instanceof Error ? error.message : String(error));
+            process.exit(1);
+        }
+    });
+    program
+        .command("log")
+        .description("顯示 App 容器 log 與遮罩後的診斷資訊")
+        .requiredOption("--host <name>", "synoagentcli profile 或 NAS 名稱")
+        .option("--dev", "查詢 Development Package Identity")
+        .action(async (options, command) => {
+        const global = command.parent?.opts() ?? {};
+        const project = resolveProject(process.cwd(), global.project);
+        const host = createNasHost({ host: options.host });
+        if (!host) {
+            console.error("找不到 NAS 憑證。請設定 synoagentcli profile 或 DSM_URL／DSM_PASSWORD。");
+            process.exit(1);
+        }
+        try {
+            const result = await followProjectLogs({ project, host, dev: options.dev });
+            if (!result.ok) {
+                console.error("套件尚未安裝。先執行 synopkgland deploy --host。");
+                process.exit(1);
+            }
+            for (const line of result.lines) {
+                console.log(line);
+            }
+            if (result.diagnostics) {
+                console.log(JSON.stringify(result.diagnostics, null, 2));
+            }
+        }
+        catch (error) {
+            console.error(error instanceof Error ? error.message : String(error));
+            process.exit(1);
+        }
+    });
+    const skill = program
+        .command("skill")
+        .description("列出或讀取隨 CLI 內建的 Agent Skill Pack");
+    skill
+        .command("path")
+        .description("輸出 Skill Pack 根目錄（供 agent 載入 SKILL.md）")
+        .action(() => {
+        console.log(resolveSkillsRoot());
+    });
+    skill
+        .command("list")
+        .description("列出漸進式 skill 與檔案路徑")
+        .action(() => {
+        console.log(formatSkillList());
+    });
+    skill
+        .command("show <id>")
+        .description("輸出指定 skill 內容（orchestrator、create、wrap、identity、files、deploy、diagnose）")
+        .action((id) => {
+        try {
+            console.log(readSkill(id));
+        }
+        catch (error) {
+            console.error(error instanceof Error ? error.message : String(error));
+            process.exit(1);
+        }
+    });
+    program
+        .command("build-spk")
+        .description("產生本機 thin SPK（未簽署）")
+        .option("-o, --output <path>", "輸出 .spk 路徑")
+        .action(async (options, command) => {
+        const global = command.parent?.opts() ?? {};
+        const project = resolveProject(process.cwd(), global.project);
+        const result = await buildSpk({
+            project,
+            outputPath: options.output ? resolve(process.cwd(), options.output) : undefined,
+        });
+        if (!result.ok) {
+            console.error(`建置失敗：${result.errors.join(", ")}`);
+            process.exit(1);
+        }
+        console.log(`已產生 ${result.outputPath}`);
+    });
+    program
+        .command("publish")
+        .description("對 Community Apps 建立 GitHub Pull Request（不上傳 SPK、不簽署）")
+        .option("--base <branch>", "PR 目標分支", "master")
+        .action(async (options, command) => {
+        const global = command.parent?.opts() ?? {};
+        const project = resolveProject(process.cwd(), global.project);
+        const communityAppsRoot = resolveCommunityAppsRoot(project.root);
+        if (!communityAppsRoot) {
+            console.error("找不到 synopkgland-community-apps/apps。請在 monorepo 根目錄執行，或設定 SYNOPKGLAND_COMMUNITY_APPS_ROOT。");
+            process.exit(1);
+        }
+        const repoRoot = dirname(communityAppsRoot);
+        try {
+            const result = await publishProject({
+                project,
+                communityAppsRoot,
+                baseBranch: options.base,
+                github: createExecGitHubCli(repoRoot, communityAppsGitHubRepo()),
+                git: createExecGitOps(repoRoot),
+            });
+            if (!result.ok) {
+                console.error(result.message ?? result.code ?? "publish 失敗。");
+                process.exit(1);
+            }
+            if (result.noChanges) {
+                console.log(result.message ?? "Community Apps 定義已是最新。");
+                return;
+            }
+            console.log(`已建立 PR：${result.prUrl}`);
+        }
+        catch (error) {
+            console.error(error instanceof Error ? error.message : String(error));
+            process.exit(1);
+        }
+    });
+    await program.parseAsync(argv);
+}

package/dist/compose/analyze.d.ts

@@ -0,0 +1,25 @@
+import type { ComposeDocument, ComposeService, ValidationError } from "../types.js";
+import { type PrivilegeFlag } from "./privilege.js";
+export interface ParsedCompose {
+    compose: ComposeDocument;
+    source: string;
+}
+export declare function loadCompose(composePath: string): ParsedCompose | null;
+export declare function listServiceNames(compose: ComposeDocument): string[];
+export declare function extractPublishedTcpPorts(service: ComposeService): number[];
+export declare function collectPublishedTcpPorts(compose: ComposeDocument): Map<number, string[]>;
+export declare function collectComposeInterpolations(compose: ComposeDocument): Set<string>;
+export declare function validateComposeSecurity(compose: ComposeDocument, composeFile: string, options: {
+    profile: "personal" | "listing";
+    declaredPrivilege: ReadonlySet<PrivilegeFlag>;
+}): ValidationError[];
+export interface HostBindContext {
+    sharedFolderParams: ReadonlySet<string>;
+    installParamNames: ReadonlySet<string>;
+}
+export declare function collectVolumeSourceInterpolations(compose: ComposeDocument): Set<string>;
+export declare function validateComposeHostBinds(compose: ComposeDocument, composeFile: string, context: HostBindContext): ValidationError[];
+export declare function validateComposeRunAs(compose: ComposeDocument, composeFile: string, context: {
+    hasSharedFolder: boolean;
+}): ValidationError[];
+export declare function validateAdminPortMapping(adminport: number, compose: ComposeDocument, composeFile: string): ValidationError[];