@synopackageland/cli 0.1.0

package/dist/deploy/share-values.d.ts

@@ -0,0 +1,20 @@
+import type { AppContract } from "../types.js";
+export declare const SHARE_VALUE_REQUIRED = "SHARE_VALUE_REQUIRED";
+export declare const SHARE_LOGICAL_NAME_REQUIRED = "SHARE_LOGICAL_NAME_REQUIRED";
+export declare const SHARE_NOT_FOUND = "SHARE_NOT_FOUND";
+export declare function sharedFolderParameterNames(contract: AppContract): string[];
+export declare function isPhysicalSharePath(value: string): boolean;
+export type ShareResolveResult = {
+    ok: true;
+    extraValues: Record<string, string>;
+} | {
+    ok: false;
+    code: string;
+    message: string;
+};
+export declare function resolveSharedFolderExtraValues(input: {
+    requiredKeys: string[];
+    provided: Record<string, string>;
+    existingEnv?: Record<string, string>;
+    lookup: (logicalName: string) => Promise<string | undefined>;
+}): Promise<ShareResolveResult>;

package/dist/deploy/share-values.js

@@ -0,0 +1,60 @@
+import { collectInstallParameters } from "../contract/load.js";
+export const SHARE_VALUE_REQUIRED = "SHARE_VALUE_REQUIRED";
+export const SHARE_LOGICAL_NAME_REQUIRED = "SHARE_LOGICAL_NAME_REQUIRED";
+export const SHARE_NOT_FOUND = "SHARE_NOT_FOUND";
+export function sharedFolderParameterNames(contract) {
+    return collectInstallParameters(contract)
+        .filter((item) => item.param.type === "shared_folder")
+        .map((item) => item.name);
+}
+export function isPhysicalSharePath(value) {
+    const trimmed = value.trim();
+    if (trimmed.startsWith("/")) {
+        return true;
+    }
+    return /(?:^|\/)volume(?:USB|SATA)?\d+/i.test(trimmed);
+}
+export async function resolveSharedFolderExtraValues(input) {
+    if (input.requiredKeys.length === 0) {
+        return { ok: true, extraValues: {} };
+    }
+    const extraValues = {};
+    const missing = [];
+    for (const key of input.requiredKeys) {
+        const raw = input.provided[key];
+        if (raw === undefined || raw.trim() === "") {
+            const existing = input.existingEnv?.[key];
+            if (typeof existing === "string" && existing.trim() !== "") {
+                continue;
+            }
+            missing.push(key);
+            continue;
+        }
+        const logical = raw.trim();
+        if (isPhysicalSharePath(logical)) {
+            return {
+                ok: false,
+                code: SHARE_LOGICAL_NAME_REQUIRED,
+                message: `Shared Folder「${key}」必須是這台 NAS 上的邏輯 Share 名，不能傳 /volume1/... 實體路徑。`,
+            };
+        }
+        const resolved = await input.lookup(logical);
+        if (!resolved || resolved.trim() === "") {
+            return {
+                ok: false,
+                code: SHARE_NOT_FOUND,
+                message: `這台 NAS 找不到 Shared Folder「${logical}」。請改傳已存在的邏輯名；不會猜測實體路徑。`,
+            };
+        }
+        extraValues[key] = resolved;
+    }
+    if (missing.length > 0) {
+        const example = `--share ${missing[0]}=photos`;
+        return {
+            ok: false,
+            code: SHARE_VALUE_REQUIRED,
+            message: `契約有 Shared Folder 槽「${missing.join("、")}」。請傳每個槽在這台 NAS 上的邏輯 Share 名（例如 ${example}），或改走會跳出 Package Center 安裝精靈的安裝。禁止以 extra_values={} 繼續，否則會 bind 空路徑（Container Manager 2202）。`,
+        };
+    }
+    return { ok: true, extraValues };
+}

package/dist/deploy/spk-info.d.ts

@@ -0,0 +1,12 @@
+export interface SpkInfo {
+    package: string;
+    version: string;
+    displayname?: string;
+    description?: string;
+    maintainer?: string;
+    install_dep_packages?: string;
+    os_min_ver?: string;
+    startable?: boolean;
+}
+export declare function parseSpkInfoContent(info: string): SpkInfo;
+export declare function readSpkInfo(spkPath: string): Promise<SpkInfo>;

package/dist/deploy/spk-info.js

@@ -0,0 +1,41 @@
+import { readFileSync, rmSync } from "node:fs";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { extractSpk } from "../build-spk/generator.js";
+function parseInfoField(info, key) {
+    const match = new RegExp(`^${key}="((?:\\\\.|[^"\\\\])*)"`, "m").exec(info);
+    if (!match) {
+        return undefined;
+    }
+    return match[1].replace(/\\"/g, '"').replace(/\\\\/g, "\\");
+}
+export function parseSpkInfoContent(info) {
+    const packageName = parseInfoField(info, "package");
+    const version = parseInfoField(info, "version");
+    if (!packageName || !version) {
+        throw new Error("SPK INFO missing package or version");
+    }
+    const startableRaw = parseInfoField(info, "startable");
+    return {
+        package: packageName,
+        version,
+        displayname: parseInfoField(info, "displayname"),
+        description: parseInfoField(info, "description"),
+        maintainer: parseInfoField(info, "maintainer"),
+        install_dep_packages: parseInfoField(info, "install_dep_packages"),
+        os_min_ver: parseInfoField(info, "os_min_ver"),
+        startable: startableRaw === undefined ? undefined : startableRaw === "yes",
+    };
+}
+export async function readSpkInfo(spkPath) {
+    const dir = mkdtempSync(join(tmpdir(), "syno-spk-info-"));
+    try {
+        await extractSpk(spkPath, dir);
+        const info = readFileSync(join(dir, "INFO"), "utf8");
+        return parseSpkInfoContent(info);
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}

package/dist/deploy/spk-version.d.ts

@@ -0,0 +1,4 @@
+import type { ProjectRoot } from "../discovery.js";
+import type { NasHost } from "../host/types.js";
+export declare function resolveDeploySpkVersion(project: ProjectRoot, host: NasHost, packageId: string): Promise<string>;
+export declare function publishDeploySpk(spkPath: string): Promise<string>;

package/dist/deploy/spk-version.js

@@ -0,0 +1,64 @@
+import { loadContract } from "../contract/load.js";
+import { comparePackageVersions } from "@synopackageland/package-source/index-manifest";
+import { resolveNextSpkVersion } from "@synopackageland/package-source/next-version";
+import { fetchPackageSourceManifest, fetchPackageSourceManifestFromR2, resolvePublishTarget, } from "@synopackageland/package-source/publish-spk";
+import { publishBuiltSpk } from "./catalog-publish.js";
+import { isDevelopmentPackageIdentity } from "./identity-shared.js";
+const LIVE_TEST_FALLBACK_ORIGIN = "https://syno-package-source-throwaway.bidacumen.workers.dev";
+function defaultSpkVersion(contractVersion) {
+    return /-\d+$/.test(contractVersion) ? contractVersion : `${contractVersion}-0001`;
+}
+function bumpBuildNumber(version) {
+    const match = /^(.+)-(\d+)$/.exec(version);
+    if (!match) {
+        return `${version}-0002`;
+    }
+    const next = String(Number(match[2]) + 1).padStart(4, "0");
+    return `${match[1]}-${next}`;
+}
+async function resolvePackageSourceManifest(origin) {
+    try {
+        const manifest = await fetchPackageSourceManifest(origin);
+        if (manifest) {
+            return manifest;
+        }
+        if (origin !== LIVE_TEST_FALLBACK_ORIGIN) {
+            return fetchPackageSourceManifest(LIVE_TEST_FALLBACK_ORIGIN);
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+async function resolveOfflineDeploySpkVersion(project, host, packageId) {
+    const contract = loadContract(project.contractPath).contract;
+    const base = defaultSpkVersion(String(contract.version ?? "1.0.0"));
+    if (!(await host.isPackageInstalled(packageId))) {
+        return base;
+    }
+    const installed = await host.getInstalledPackageVersion?.(packageId);
+    return installed ? bumpBuildNumber(installed) : base;
+}
+export async function resolveDeploySpkVersion(project, host, packageId) {
+    if (host.installationId !== "live-nas" || isDevelopmentPackageIdentity(packageId)) {
+        return resolveOfflineDeploySpkVersion(project, host, packageId);
+    }
+    const contract = loadContract(project.contractPath).contract;
+    const target = resolvePublishTarget();
+    const manifest = (await fetchPackageSourceManifestFromR2(target)) ??
+        (await resolvePackageSourceManifest(target.origin));
+    let version = resolveNextSpkVersion(String(contract.version ?? "1.0.0"), packageId, manifest);
+    const installed = await host.getInstalledPackageVersion?.(packageId);
+    if (installed) {
+        const installedNext = bumpBuildNumber(installed);
+        if (comparePackageVersions(installedNext, version) > 0) {
+            version = installedNext;
+        }
+    }
+    return version;
+}
+export async function publishDeploySpk(spkPath) {
+    const published = await publishBuiltSpk(spkPath);
+    return published.version;
+}

package/dist/dev.d.ts

@@ -0,0 +1,13 @@
+import type { ProjectRoot } from "./discovery.js";
+import type { ComposeRunner } from "./compose/runner.js";
+export interface DevOptions {
+    project: ProjectRoot;
+    filesRoot?: string;
+    composeRunner?: ComposeRunner;
+}
+export interface DevHandle {
+    brokerBaseUrl: string;
+    bootstrapPath: string;
+    close(): Promise<void>;
+}
+export declare function runDev(options: DevOptions): Promise<DevHandle>;

package/dist/dev.js

@@ -0,0 +1,31 @@
+import { loadContract } from "./contract/load.js";
+import { writeMockBrokerBootstrap } from "./mock-broker/bootstrap.js";
+import { startMockBroker } from "./mock-broker/server.js";
+import { createDockerComposeRunner } from "./compose/runner.js";
+export async function runDev(options) {
+    const parsed = loadContract(options.project.contractPath);
+    const packageId = String(parsed.contract.package);
+    const broker = await startMockBroker({
+        packageId,
+        filesRoot: options.filesRoot,
+    });
+    const bootstrapPath = writeMockBrokerBootstrap(options.project.root, {
+        brokerBaseUrl: broker.baseUrl,
+        jwksUrl: broker.jwksUrl,
+        packageId,
+        mock: true,
+    });
+    const composeRunner = options.composeRunner ?? createDockerComposeRunner();
+    await composeRunner.up(options.project.root);
+    await composeRunner.waitReady(options.project.root);
+    return {
+        brokerBaseUrl: broker.baseUrl,
+        bootstrapPath,
+        close: async () => {
+            if (composeRunner.down) {
+                await composeRunner.down(options.project.root);
+            }
+            await broker.close();
+        },
+    };
+}

package/dist/discovery.d.ts

@@ -0,0 +1,8 @@
+export declare const CONTRACT_FILENAME = "synology-app.yaml";
+export declare const COMPOSE_FILENAME = "compose.yaml";
+export interface ProjectRoot {
+    root: string;
+    contractPath: string;
+    composePath: string;
+}
+export declare function findProjectRoot(startDir: string): ProjectRoot | null;

package/dist/discovery.js

@@ -0,0 +1,22 @@
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+export const CONTRACT_FILENAME = "synology-app.yaml";
+export const COMPOSE_FILENAME = "compose.yaml";
+export function findProjectRoot(startDir) {
+    let current = resolve(startDir);
+    while (true) {
+        const contractPath = join(current, CONTRACT_FILENAME);
+        if (existsSync(contractPath)) {
+            return {
+                root: current,
+                contractPath,
+                composePath: join(current, COMPOSE_FILENAME),
+            };
+        }
+        const parent = dirname(current);
+        if (parent === current) {
+            return null;
+        }
+        current = parent;
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,6 @@
+import type { SourceSpan, ValidationError } from "./types.js";
+export declare function makeError(code: string, span: SourceSpan, message: string, suggestion: string, severity?: "error" | "warning"): ValidationError;
+export declare function contractSpan(file: string, line: number, column: number, path?: string): SourceSpan;
+export declare function composeSpan(file: string, line: number, column: number, path?: string): SourceSpan;
+export declare function formatError(error: ValidationError): string;
+export declare function formatErrors(errors: ValidationError[]): string;

package/dist/errors.js

@@ -0,0 +1,18 @@
+export function makeError(code, span, message, suggestion, severity = "error") {
+    return { code, span, message, suggestion, severity };
+}
+export function contractSpan(file, line, column, path) {
+    return { file, line, column, path };
+}
+export function composeSpan(file, line, column, path) {
+    return { file, line, column, path };
+}
+export function formatError(error) {
+    const location = error.span.path
+        ? `${error.span.file}:${error.span.line}:${error.span.column} (${error.span.path})`
+        : `${error.span.file}:${error.span.line}:${error.span.column}`;
+    return `[${error.code}] ${location}\n${error.message}\n建議：${error.suggestion}`;
+}
+export function formatErrors(errors) {
+    return errors.map(formatError).join("\n\n");
+}

package/dist/host/broker-paths.d.ts

@@ -0,0 +1 @@
+export declare const IDENTITY_CGI_PATH = "/webman/3rdparty/SynoPkgLandService/index.cgi";

package/dist/host/broker-paths.js

@@ -0,0 +1 @@
+export const IDENTITY_CGI_PATH = "/webman/3rdparty/SynoPkgLandService/index.cgi";

package/dist/host/catalog-install.d.ts

@@ -0,0 +1,59 @@
+interface CatalogPackageEntry {
+    package: string;
+    version: string;
+    link: string;
+    md5: string;
+    size: number;
+    beta?: boolean;
+    qinst?: boolean;
+    deppkgs?: string | Record<string, unknown> | null;
+    breakpkgs?: unknown;
+    replacepkgs?: unknown;
+}
+export interface CatalogInstallOptions {
+    dsmOrigin: string;
+    cookieHeader: string;
+    packageId: string;
+    profileName?: string;
+    expectedVersion?: string;
+    packageSourceOrigin?: string;
+    extraValues?: Record<string, string>;
+}
+export interface InstalledPackageState {
+    installed: boolean;
+    version?: string;
+    status?: string;
+}
+export interface UploadedCatalogPackage {
+    id: string;
+    taskId: string;
+}
+export declare function packageStateFromListPayload(payload: unknown, packageId: string): InstalledPackageState | undefined;
+export declare function fetchInstalledPackageState(dsmOrigin: string, cookieHeader: string, packageId: string): Promise<InstalledPackageState | undefined>;
+export declare function waitForInstalledVersion(readState: () => InstalledPackageState | undefined | Promise<InstalledPackageState | undefined>, options: {
+    packageId: string;
+    expectedVersion?: string;
+    deadlineMs?: number;
+    pollMs?: number;
+}): Promise<void>;
+export declare function catalogInstallationRequests(entry: Pick<CatalogPackageEntry, "package" | "version" | "size" | "beta" | "link" | "md5" | "qinst" | "deppkgs" | "breakpkgs" | "replacepkgs">, installed: boolean, sid: string, volumePath?: string): {
+    check: Record<string, string>;
+    install: Record<string, string>;
+};
+export declare function catalogCompoundSteps(uploaded: UploadedCatalogPackage, entry: Pick<CatalogPackageEntry, "version" | "size">, options: {
+    blupgrade: boolean;
+    extraValues?: Record<string, string>;
+}): unknown[];
+export declare function catalogUpgradeCompoundSteps(uploaded: UploadedCatalogPackage, entry: Pick<CatalogPackageEntry, "version" | "size">, extraValues?: Record<string, string>): unknown[];
+export interface LocalSpkInstallOptions {
+    dsmOrigin: string;
+    cookieHeader: string;
+    packageId: string;
+    spkPath: string;
+    version: string;
+    profileName?: string;
+    extraValues?: Record<string, string>;
+}
+export declare function installPackageFromLocalSpk(options: LocalSpkInstallOptions): Promise<void>;
+export declare function installPackageFromCatalog(options: CatalogInstallOptions): Promise<void>;
+export {};