@synopackageland/cli 0.1.0

package/dist/skill.js

@@ -0,0 +1,50 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const SKILL_CATALOG = [
+    { id: "orchestrator", file: "SKILL.md", when: "永遠先讀" },
+    { id: "create", file: "reference/create.md", when: "從零或一句話開始" },
+    { id: "wrap", file: "reference/wrap.md", when: "已有 Compose 或要補契約" },
+    { id: "identity", file: "reference/identity.md", when: "需要 DSM 登入者" },
+    { id: "files", file: "reference/files.md", when: "需要 NAS 檔案" },
+    { id: "deploy", file: "reference/deploy.md", when: "要放到 NAS" },
+    { id: "diagnose", file: "reference/diagnose.md", when: "validate／deploy／Open 失敗" },
+];
+export function resolveSkillsRoot() {
+    const moduleDir = dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+        join(moduleDir, "..", "skills"),
+        join(moduleDir, "skills"),
+    ];
+    for (const candidate of candidates) {
+        if (existsSync(join(candidate, "SKILL.md"))) {
+            return candidate;
+        }
+    }
+    throw new Error("找不到 Skill Pack。請重新安裝 @synopackageland/cli。");
+}
+export function listSkills() {
+    return [...SKILL_CATALOG];
+}
+export function skillPath(id) {
+    const entry = SKILL_CATALOG.find((item) => item.id === id);
+    if (!entry) {
+        throw new Error(`未知 skill：${id}`);
+    }
+    const path = join(resolveSkillsRoot(), entry.file);
+    if (!existsSync(path)) {
+        throw new Error(`Skill 檔案不存在：${entry.file}`);
+    }
+    return path;
+}
+export function readSkill(id) {
+    return readFileSync(skillPath(id), "utf8");
+}
+export function formatSkillList() {
+    const root = resolveSkillsRoot();
+    const lines = [`Skill Pack：${root}`, ""];
+    for (const entry of SKILL_CATALOG) {
+        lines.push(`${entry.id}\t${entry.when}\t${entry.file}`);
+    }
+    return lines.join("\n");
+}

package/dist/templates/compose-import/compose.yaml

@@ -0,0 +1,11 @@
+services:
+  app:
+    image: hello-world:latest
+    user: "${RUN_AS_UID}:${RUN_AS_GID}"
+    volumes:
+      - "${MEDIA_SHARE}:/media"
+      - "${BACKUP_SHARE}:/backup"
+      - "upstream_data:/var/lib/upstream"
+
+volumes:
+  upstream_data:

package/dist/templates/compose-import/synology-app.yaml

@@ -0,0 +1,15 @@
+schema: 1
+package: com.synology.compose.import
+version: 0.1.0
+displayname: Compose Import
+description: Start from an existing Compose file and select two Shared Folders at install time.
+maintainer: Syno Package Land
+os_min_ver: "7.2-69057"
+
+install:
+  MEDIA_SHARE:
+    type: shared_folder
+  BACKUP_SHARE:
+    type: shared_folder
+  RUN_AS:
+    type: dsm_user

package/dist/templates/hello-files/compose.yaml

@@ -0,0 +1,8 @@
+services:
+  worker:
+    image: alpine:3.20
+    command: ["sleep", "infinity"]
+    user: "${RUN_AS_UID}:${RUN_AS_GID}"
+    volumes:
+      - "${MEDIA_SHARE}/data:/data:ro"
+      - "${SYNOPKG_PKGVAR}/state:/state"

package/dist/templates/hello-files/synology-app.yaml

@@ -0,0 +1,13 @@
+schema: 1
+package: com.synology.hello.files
+version: 0.1.0
+displayname: Hello Files
+description: A minimal headless app with a Shared Folder mount.
+maintainer: Syno Package Land
+os_min_ver: "7.2-69057"
+
+install:
+  MEDIA_SHARE:
+    type: shared_folder
+  RUN_AS:
+    type: dsm_user

package/dist/templates/hello-web/compose.yaml

@@ -0,0 +1,7 @@
+services:
+  web:
+    image: nginx:alpine
+    ports:
+      - "8080:80"
+    volumes:
+      - "${SYNOPKG_PKGVAR}/html:/usr/share/nginx/html:ro"

package/dist/templates/hello-web/html/app.js

@@ -0,0 +1,23 @@
+import { createSynologyClient } from "./sdk.js";
+
+const status = document.getElementById("status");
+const userEl = document.getElementById("user");
+
+const client = createSynologyClient();
+
+try {
+  await client.auth.requireLogin();
+  const user = await client.auth.getCurrentUser();
+  if (status) {
+    status.textContent = "Signed in with DSM";
+  }
+  if (userEl) {
+    userEl.textContent = user.username;
+  }
+} catch (error) {
+  const code = error && typeof error === "object" && "code" in error ? String(error.code) : "";
+  const message = error instanceof Error ? error.message : String(error);
+  if (status) {
+    status.textContent = code === "UNAUTHENTICATED" ? "DSM login required" : message;
+  }
+}

package/dist/templates/hello-web/html/index.html

@@ -0,0 +1,15 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Hello Web</title>
+  </head>
+  <body>
+    <h1>Hello Web</h1>
+    <p id="status">Opening with your DSM session…</p>
+    <p id="user"></p>
+    <script src="./bootstrap.js"></script>
+    <script type="module" src="./app.js"></script>
+  </body>
+</html>

package/dist/templates/hello-web/html/sdk.js

@@ -0,0 +1,68 @@
+export function createSynologyClient(options = {}) {
+  const bootstrap =
+    options.bootstrap ??
+    globalThis.__SYNOLOGY_BOOTSTRAP__ ??
+    (options.brokerBaseUrl
+      ? {
+          brokerBaseUrl: options.brokerBaseUrl,
+          jwksUrl: `${String(options.brokerBaseUrl).replace(/\/$/, "")}/.well-known/jwks.json`,
+          packageId: "com.synology.hello.web",
+        }
+      : undefined);
+  if (!bootstrap?.brokerBaseUrl) {
+    throw new Error("缺少 Platform SDK bootstrap。");
+  }
+  const apiBase = `${String(bootstrap.brokerBaseUrl).replace(/\/$/, "")}/api/v1`;
+  let accessToken = null;
+
+  async function parseJson(response) {
+    const text = await response.text();
+    const body = text ? JSON.parse(text) : {};
+    if (!response.ok) {
+      const error = body.error ?? {};
+      const err = new Error(error.message ?? `Broker request failed with status ${response.status}`);
+      err.code = error.code;
+      err.details = error.details;
+      throw err;
+    }
+    return body;
+  }
+
+  return {
+    auth: {
+      async requireLogin() {
+        const result = await parseJson(
+          await fetch(`${apiBase}/auth/login`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            credentials: "include",
+            body: JSON.stringify({ packageId: bootstrap.packageId }),
+          }),
+        );
+        accessToken = result.accessToken;
+        return result.user;
+      },
+      async getSession() {
+        if (!accessToken) {
+          return null;
+        }
+        const result = await parseJson(
+          await fetch(`${apiBase}/session`, {
+            headers: { authorization: `Bearer ${accessToken}` },
+            credentials: "include",
+          }),
+        );
+        return result.user;
+      },
+      async getCurrentUser() {
+        const session = await this.getSession();
+        if (!session) {
+          const err = new Error("尚未建立有效身份。");
+          err.code = "UNAUTHENTICATED";
+          throw err;
+        }
+        return session;
+      },
+    },
+  };
+}

package/dist/templates/hello-web/synology-app.yaml

@@ -0,0 +1,13 @@
+schema: 1
+package: com.synology.hello.web
+version: 0.1.0
+displayname: Hello Web
+description: A minimal Syno Package Land web app template.
+maintainer: Syno Package Land
+os_min_ver: "7.2-69057"
+adminprotocol: http
+adminport: 8080
+adminurl: /
+integration:
+  web:
+    launch: dsm-window

package/dist/templates/hello-web-page/compose.yaml

@@ -0,0 +1,7 @@
+services:
+  web:
+    image: nginx:alpine
+    ports:
+      - "8080:80"
+    volumes:
+      - "${SYNOPKG_PKGVAR}/html:/usr/share/nginx/html:ro"

package/dist/templates/hello-web-page/html/app.js

@@ -0,0 +1,23 @@
+import { createSynologyClient } from "./sdk.js";
+
+const status = document.getElementById("status");
+const userEl = document.getElementById("user");
+
+const client = createSynologyClient();
+
+try {
+  await client.auth.requireLogin();
+  const user = await client.auth.getCurrentUser();
+  if (status) {
+    status.textContent = "Signed in with DSM";
+  }
+  if (userEl) {
+    userEl.textContent = user.username;
+  }
+} catch (error) {
+  const code = error && typeof error === "object" && "code" in error ? String(error.code) : "";
+  const message = error instanceof Error ? error.message : String(error);
+  if (status) {
+    status.textContent = code === "UNAUTHENTICATED" ? "DSM login required" : message;
+  }
+}

package/dist/templates/hello-web-page/html/index.html

@@ -0,0 +1,15 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Hello Web Page</title>
+  </head>
+  <body>
+    <h1>Hello Web Page</h1>
+    <p id="status">Opening with your DSM session…</p>
+    <p id="user"></p>
+    <script src="./bootstrap.js"></script>
+    <script type="module" src="./app.js"></script>
+  </body>
+</html>

package/dist/templates/hello-web-page/html/sdk.js

@@ -0,0 +1,68 @@
+export function createSynologyClient(options = {}) {
+  const bootstrap =
+    options.bootstrap ??
+    globalThis.__SYNOLOGY_BOOTSTRAP__ ??
+    (options.brokerBaseUrl
+      ? {
+          brokerBaseUrl: options.brokerBaseUrl,
+          jwksUrl: `${String(options.brokerBaseUrl).replace(/\/$/, "")}/.well-known/jwks.json`,
+          packageId: "com.synology.hello.web.page",
+        }
+      : undefined);
+  if (!bootstrap?.brokerBaseUrl) {
+    throw new Error("缺少 Platform SDK bootstrap。");
+  }
+  const apiBase = `${String(bootstrap.brokerBaseUrl).replace(/\/$/, "")}/api/v1`;
+  let accessToken = null;
+
+  async function parseJson(response) {
+    const text = await response.text();
+    const body = text ? JSON.parse(text) : {};
+    if (!response.ok) {
+      const error = body.error ?? {};
+      const err = new Error(error.message ?? `Broker request failed with status ${response.status}`);
+      err.code = error.code;
+      err.details = error.details;
+      throw err;
+    }
+    return body;
+  }
+
+  return {
+    auth: {
+      async requireLogin() {
+        const result = await parseJson(
+          await fetch(`${apiBase}/auth/login`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            credentials: "include",
+            body: JSON.stringify({ packageId: bootstrap.packageId }),
+          }),
+        );
+        accessToken = result.accessToken;
+        return result.user;
+      },
+      async getSession() {
+        if (!accessToken) {
+          return null;
+        }
+        const result = await parseJson(
+          await fetch(`${apiBase}/session`, {
+            headers: { authorization: `Bearer ${accessToken}` },
+            credentials: "include",
+          }),
+        );
+        return result.user;
+      },
+      async getCurrentUser() {
+        const session = await this.getSession();
+        if (!session) {
+          const err = new Error("尚未建立有效身份。");
+          err.code = "UNAUTHENTICATED";
+          throw err;
+        }
+        return session;
+      },
+    },
+  };
+}

package/dist/templates/hello-web-page/synology-app.yaml

@@ -0,0 +1,13 @@
+schema: 1
+package: com.synology.hello.web.page
+version: 0.1.0
+displayname: Hello Web Page
+description: A Syno Package Land web app template that opens in a new browser page.
+maintainer: Syno Package Land
+os_min_ver: "7.2-69057"
+adminprotocol: http
+adminport: 8080
+adminurl: /
+integration:
+  web:
+    launch: new-page

package/dist/test-command.d.ts

@@ -0,0 +1,13 @@
+import type { ProjectRoot } from "./discovery.js";
+import type { ComposeRunner } from "./compose/runner.js";
+export interface TestProjectOptions {
+    project: ProjectRoot;
+    composeRunner?: ComposeRunner;
+}
+export interface TestProjectResult {
+    ok: boolean;
+    composeInvoked: boolean;
+    errors: string[];
+}
+export declare function testProject(options: TestProjectOptions): Promise<TestProjectResult>;
+export { materializeComposePaths, composeEnvDirsExist, prepareComposeEnvironment } from "./compose/env.js";

package/dist/test-command.js

@@ -0,0 +1,26 @@
+import { materializeComposePaths, composeEnvDirsExist } from "./compose/env.js";
+import { validateProject } from "./validate.js";
+import { createDockerComposeRunner } from "./compose/runner.js";
+export async function testProject(options) {
+    const validation = validateProject(options.project);
+    if (!validation.ok) {
+        return {
+            ok: false,
+            composeInvoked: false,
+            errors: validation.errors.map((e) => e.code),
+        };
+    }
+    materializeComposePaths(options.project.root, options.project.composePath);
+    const composeRunner = options.composeRunner ?? createDockerComposeRunner();
+    await composeRunner.up(options.project.root);
+    await composeRunner.waitReady(options.project.root);
+    if (!composeEnvDirsExist(options.project.root)) {
+        return {
+            ok: false,
+            composeInvoked: true,
+            errors: ["COMPOSE_ENV_MISSING"],
+        };
+    }
+    return { ok: true, composeInvoked: true, errors: [] };
+}
+export { materializeComposePaths, composeEnvDirsExist, prepareComposeEnvironment } from "./compose/env.js";

package/dist/test-host.d.ts

@@ -0,0 +1,13 @@
+import type { ProjectRoot } from "./discovery.js";
+import type { NasHost } from "./host/types.js";
+export interface TestProjectOnHostOptions {
+    project: ProjectRoot;
+    host: NasHost;
+    dev?: boolean;
+    cookieHeader?: string;
+}
+export interface TestProjectOnHostResult {
+    ok: boolean;
+    message?: string;
+}
+export declare function testProjectOnHost(options: TestProjectOnHostOptions): Promise<TestProjectOnHostResult>;

package/dist/test-host.js

@@ -0,0 +1,24 @@
+import { validateProject } from "./validate.js";
+import { resolveDeployIdentity } from "./deploy/identity.js";
+export async function testProjectOnHost(options) {
+    const validation = validateProject(options.project);
+    if (!validation.ok) {
+        return { ok: false, message: validation.errors.map((e) => e.code).join(", ") };
+    }
+    const identity = resolveDeployIdentity(options.project, { dev: options.dev });
+    const installed = await options.host.isPackageInstalled(identity.packageId);
+    if (!installed) {
+        return {
+            ok: false,
+            message: `尚未部署到 ${options.host.dsmOrigin}。下一步：synopkgland deploy --host <nas>${options.dev ? " --dev" : ""}`,
+        };
+    }
+    const smoke = await options.host.smokeRequireLogin({
+        packageIdentity: identity.packageId,
+        cookieHeader: options.cookieHeader ?? "id=fake; did=fake",
+    });
+    if (!smoke.ok) {
+        return { ok: false, message: "Open smoke 失敗：requireLogin 未取得 DSM 使用者。" };
+    }
+    return { ok: true };
+}

package/dist/types.d.ts

@@ -0,0 +1,59 @@
+export interface SourceSpan {
+    file: string;
+    line: number;
+    column: number;
+    path?: string;
+}
+export interface ValidationError {
+    code: string;
+    span: SourceSpan;
+    message: string;
+    suggestion: string;
+    severity?: "error" | "warning";
+}
+export interface ValidationResult {
+    ok: boolean;
+    errors: ValidationError[];
+    warnings?: ValidationError[];
+}
+export interface AppContract {
+    schema?: unknown;
+    package?: unknown;
+    version?: unknown;
+    displayname?: unknown;
+    description?: unknown;
+    maintainer?: unknown;
+    os_min_ver?: unknown;
+    adminport?: unknown;
+    adminprotocol?: unknown;
+    adminurl?: unknown;
+    install?: Record<string, InstallParameter>;
+    integration?: unknown;
+    permissions?: unknown;
+    [key: string]: unknown;
+}
+export interface InstallParameter {
+    type?: string;
+    default?: unknown;
+    generate?: boolean;
+}
+export interface ComposeService {
+    image?: string;
+    ports?: unknown;
+    volumes?: unknown;
+    environment?: unknown;
+    privileged?: boolean;
+    network_mode?: string;
+    devices?: unknown;
+    cap_add?: unknown;
+    pid?: string;
+    ipc?: string;
+    depends_on?: unknown;
+    [key: string]: unknown;
+}
+export interface ComposeDocument {
+    services?: Record<string, ComposeService>;
+    secrets?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export type TemplateName = "hello-web" | "hello-web-page" | "hello-files" | "compose-import";

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/validate.d.ts

@@ -0,0 +1,8 @@
+import type { ValidationResult } from "./types.js";
+import { type ProjectRoot } from "./discovery.js";
+export type AnalyzerProfile = "personal" | "listing";
+export declare function validateProject(project: ProjectRoot, options?: {
+    profile?: AnalyzerProfile;
+}): ValidationResult;
+export { findProjectRoot } from "./discovery.js";
+export type { ProjectRoot } from "./discovery.js";

package/dist/validate.js

@@ -0,0 +1,103 @@
+import { existsSync } from "node:fs";
+import { collectInstallParameters, loadContract } from "./contract/load.js";
+import { validateContract } from "./contract/validate.js";
+import { collectComposeInterpolations, collectVolumeSourceInterpolations, loadCompose, validateAdminPortMapping, validateComposeHostBinds, validateComposeRunAs, validateComposeSecurity, } from "./compose/analyze.js";
+import { COMPOSE_FILENAME, CONTRACT_FILENAME } from "./discovery.js";
+import { declaredPrivilegeFlags } from "./compose/privilege.js";
+export function validateProject(project, options = {}) {
+    const profile = options.profile ?? "personal";
+    const errors = [];
+    const contractFile = CONTRACT_FILENAME;
+    const composeFile = COMPOSE_FILENAME;
+    const parsed = loadContract(project.contractPath);
+    errors.push(...validateContract(parsed, contractFile));
+    if (!existsSync(project.composePath)) {
+        errors.push({
+            code: "COMPOSE_MISSING",
+            span: { file: composeFile, line: 1, column: 1 },
+            message: "找不到 compose.yaml。",
+            suggestion: "請在專案根目錄建立 compose.yaml。",
+        });
+        return { ok: false, errors };
+    }
+    const parsedCompose = loadCompose(project.composePath);
+    if (!parsedCompose) {
+        return { ok: false, errors };
+    }
+    errors.push(...validateComposeSecurity(parsedCompose.compose, composeFile, {
+        profile,
+        declaredPrivilege: declaredPrivilegeFlags(parsed.contract),
+    }));
+    const installParams = collectInstallParameters(parsed.contract);
+    const sharedFolderParams = new Set(installParams.filter(({ param }) => param.type === "shared_folder").map(({ name }) => name));
+    const installParamNames = new Set(installParams.map(({ name }) => name));
+    errors.push(...validateComposeHostBinds(parsedCompose.compose, composeFile, {
+        sharedFolderParams,
+        installParamNames,
+    }));
+    if (typeof parsed.contract.adminport === "number") {
+        errors.push(...validateAdminPortMapping(parsed.contract.adminport, parsedCompose.compose, composeFile));
+    }
+    const interpolations = collectComposeInterpolations(parsedCompose.compose);
+    const volumeSourceVars = collectVolumeSourceInterpolations(parsedCompose.compose);
+    const dsmUserParams = installParams.filter(({ param }) => param.type === "dsm_user");
+    const hasSharedFolder = sharedFolderParams.size > 0;
+    if (dsmUserParams.length > 1) {
+        errors.push({
+            code: "CONTRACT_DSM_USER_DUPLICATE",
+            span: { file: contractFile, line: 1, column: 1, path: "install" },
+            message: "每顆 App 至多一個 dsm_user。",
+            suggestion: "請只保留一個 Container Run-as 參數。",
+        });
+    }
+    if (hasSharedFolder && dsmUserParams.length === 0) {
+        errors.push({
+            code: "DSM_USER_REQUIRED",
+            span: { file: contractFile, line: 1, column: 1, path: "install" },
+            message: "有 Shared Folder 時必須宣告恰好一個 dsm_user 作為 Container Run-as。",
+            suggestion: "請新增 install.<NAME>.type: dsm_user，Compose 引用 ${NAME_UID}:${NAME_GID}。",
+            severity: profile === "listing" ? "error" : "warning",
+        });
+    }
+    errors.push(...validateComposeRunAs(parsedCompose.compose, composeFile, { hasSharedFolder }).map((item) => item.code === "COMPOSE_USER_ROOT_FORBIDDEN"
+        ? { ...item, severity: (profile === "listing" ? "error" : "warning") }
+        : item));
+    for (const { name, param } of installParams) {
+        const referenced = param.type === "shared_folder" ? volumeSourceVars.has(name) : interpolations.has(name);
+        if ((param.type === "string" || param.type === "boolean" || param.type === "shared_folder") &&
+            !referenced) {
+            errors.push({
+                code: "INSTALL_PARAMETER_UNREFERENCED",
+                span: {
+                    file: contractFile,
+                    line: 1,
+                    column: 1,
+                    path: `install.${name}`,
+                },
+                message: `Install Parameter「${name}」未在 Compose 中被引用。`,
+                suggestion: `請在 compose.yaml 以 \${${name}} 引用此參數。`,
+            });
+        }
+        if (param.type === "dsm_user") {
+            const uidName = `${name}_UID`;
+            const gidName = `${name}_GID`;
+            if (!interpolations.has(uidName) || !interpolations.has(gidName)) {
+                errors.push({
+                    code: "INSTALL_DSM_USER_UNREFERENCED",
+                    span: {
+                        file: contractFile,
+                        line: 1,
+                        column: 1,
+                        path: `install.${name}`,
+                    },
+                    message: `dsm_user「${name}」必須在 Compose 以 \${${uidName}} 與 \${${gidName}} 引用。`,
+                    suggestion: `請把容器 user 或 PUID/PGID 設成 \${${uidName}}:\${${gidName}}。`,
+                });
+            }
+        }
+    }
+    const warnings = errors.filter((item) => item.severity === "warning");
+    const hardErrors = errors.filter((item) => item.severity !== "warning");
+    return { ok: hardErrors.length === 0, errors: hardErrors, warnings };
+}
+export { findProjectRoot } from "./discovery.js";

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@synopackageland/cli",
+  "version": "0.1.0",
+  "description": "Syno Package Land Developer Kit CLI",
+  "type": "module",
+  "bin": {
+    "synopkgland": "dist/bin.js"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "schema",
+    "skills"
+  ],
+  "scripts": {
+    "build": "tsc && node scripts/copy-templates.mjs",
+    "test": "npm run build && node --import tsx --test test/**/*.test.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "dependencies": {
+    "@synopackageland/dev-sdk": "0.1.0",
+    "@synopackageland/package-source": "0.1.0",
+    "ajv": "^8.17.1",
+    "commander": "^13.1.0",
+    "jose": "^6.0.10",
+    "tar": "^7.4.3",
+    "yaml": "^2.7.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.10",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.2"
+  }
+}