@permute/sdk 0.6.0 → 0.7.0

package/dist/deploy.js

@@ -1,120 +1,197 @@
-import { lstat, readdir, open } from 'node:fs/promises';
-import { constants } from 'node:fs';
-import { join } from 'node:path';
+import { lstat, readdir, mkdir, writeFile, realpath } from 'node:fs/promises';
+import { join, dirname, resolve, basename } from 'node:path';
 import { createHash } from 'node:crypto';
 import { isDeepStrictEqual } from 'node:util';
 import { Ajv } from 'ajv';
 import { PermuteApiError } from './errors.js';
 import { publicApiRoutes } from './generated/runtime-contract.js';
+import { readLocalFile, SourceFileSelection } from './sourceFiles.js';
 const ajv = new Ajv({ strict: false, allErrors: true, validateFormats: false });
 const validateUploads = ajv.compile(publicApiRoutes.appsUploadsCreate.bodySchema);
 const validateSite = ajv.compile(publicApiRoutes.appsSiteUpdate.bodySchema);
+const validateSource = ajv.compile(publicApiRoutes.appsSiteUpdate.bodySchema.properties.source);
 function conflict(message) {
     throw new PermuteApiError({ status: 409, code: 'deployment_conflict', message });
 }
-/** Node/Bun only. Validate the complete build before making any upload or draft mutation. */
-async function readBuild(directory, body, spa, signal) {
+/** Capture exact bytes once, before any upload or draft mutation. */
+async function readDirectory(directory, validate, signal, source) {
     const entries = [];
-    const walk = async (absolutePath, path) => {
+    const walk = async (absolutePath, path, ancestors) => {
         signal?.throwIfAborted();
-        const stat = await lstat(absolutePath);
-        if (stat.isSymbolicLink())
-            throw new Error(`Build contains a symbolic link: ${path || directory}`);
+        if (path && source?.blocked(path))
+            return;
+        let stat = await lstat(absolutePath);
+        if (path && source && (await source.ignored(path, stat.isDirectory(), absolutePath)))
+            return;
+        if (stat.isSymbolicLink()) {
+            if (!source)
+                throw new Error(`App directory contains a symbolic link: ${path || directory}`);
+            absolutePath = await source.resolveLink(absolutePath);
+            stat = await lstat(absolutePath);
+            if (await source.ignored(path, stat.isDirectory(), absolutePath))
+                return;
+        }
         if (stat.isDirectory()) {
+            const realDirectory = await realpath(absolutePath);
+            if (ancestors.has(realDirectory))
+                throw new Error(`Source symlink cycle: ${path}`);
+            const parents = new Set([...ancestors, realDirectory]);
             for (const name of (await readdir(absolutePath)).sort()) {
-                await walk(join(absolutePath, name), path ? `${path}/${name}` : name);
+                await walk(join(absolutePath, name), path ? `${path}/${name}` : name, parents);
             }
         }
         else if (stat.isFile() && path) {
-            entries.push({ path, absolutePath, size: stat.size, sha256: '0'.repeat(64) });
-            if (!validateUploads({ files: entries.map(({ absolutePath: _, ...file }) => file) })) {
+            entries.push({
+                path,
+                absolutePath,
+                size: stat.size,
+                sha256: '0'.repeat(64),
+                ...(source && (stat.mode & 0o111) !== 0 ? { executable: true } : {}),
+            });
+            if (entries.reduce((total, file) => total + file.size, 0) > 50 * 1024 * 1024 ||
+                !validateUploads({ files: entries.map(({ absolutePath: _, executable: __, ...file }) => file) })) {
                 throw new PermuteApiError({
                     status: 0,
                     code: 'invalid_build',
-                    message: 'Build files exceed app limits or contain an unsupported path.',
+                    message: 'App files exceed size limits or contain an unsupported path.',
                     details: validateUploads.errors,
                 });
             }
         }
         else
-            throw new Error(`Unsupported build entry: ${path || directory}`);
+            throw new Error(`Unsupported app file: ${path || directory}`);
     };
-    await walk(directory, '');
+    await walk(directory, '', new Set());
     const manifest = entries.map(({ absolutePath: _, ...file }) => file);
     // JSON Schema cannot express the server's manifest refinements. Check these before uploading.
-    if (!manifest.some((file) => file.path === 'index.html') ||
-        manifest.reduce((total, file) => total + file.size, 0) > 50 * 1024 * 1024 ||
-        new Set(body.actions?.map((action) => action.actionId)).size !== (body.actions?.length ?? 0) ||
-        !validateSite({ ...body, site: { files: manifest, spa } })) {
+    if (!validate(manifest)) {
         throw new PermuteApiError({
             status: 0,
             code: 'invalid_build',
-            message: 'Invalid app build or bindings. Include index.html, stay within 50 MiB, and use valid app settings.',
-            details: validateSite.errors,
+            message: 'Invalid app files or settings. Check file paths, size limits and build instructions.',
         });
     }
     const files = [];
     for (const entry of entries) {
         signal?.throwIfAborted();
-        const file = await open(entry.absolutePath, constants.O_RDONLY | constants.O_NOFOLLOW);
-        try {
-            const stat = await file.stat();
-            if (!stat.isFile() || stat.size !== entry.size)
-                throw new Error(`Build changed: ${entry.path}`);
-            const data = Buffer.alloc(entry.size + 1);
-            let length = 0;
-            while (length < data.byteLength) {
-                signal?.throwIfAborted();
-                const { bytesRead } = await file.read(data, length, data.byteLength - length, null);
-                if (!bytesRead)
-                    break;
-                length += bytesRead;
-            }
-            if (length !== entry.size)
-                throw new Error(`Build changed: ${entry.path}`);
-            files.push({ path: entry.path, data: data.subarray(0, length) });
-        }
-        finally {
-            await file.close();
-        }
+        const data = source?.ignoreContents(entry.path) ?? (await readLocalFile(entry.absolutePath, entry.size, signal));
+        if (data.length !== entry.size)
+            throw new Error(`App file changed: ${entry.path}`);
+        files.push({ path: entry.path, data, ...(entry.executable ? { executable: true } : {}) });
     }
     return files;
 }
+function validSource(source) {
+    if (!validateSource(source))
+        return false;
+    const paths = source.files.map((file) => file.path.toLowerCase());
+    return (safeSourcePath(source.build.outputDirectory) &&
+        source.files.reduce((total, file) => total + file.size, 0) <= 50 * 1024 * 1024 &&
+        new Set(paths).size === paths.length &&
+        paths.every((path) => safeSourcePath(path) &&
+            !paths.some((other) => other !== path && other.startsWith(`${path}/`)) &&
+            path !== source.build.outputDirectory.toLowerCase() &&
+            !path.startsWith(`${source.build.outputDirectory.toLowerCase()}/`)));
+}
+function safeSourcePath(path) {
+    return (!SourceFileSelection.excluded(path) &&
+        path
+            .split('/')
+            .every((part) => part !== '.' &&
+            part !== '..' &&
+            !part.endsWith('.') &&
+            !part.endsWith(' ') &&
+            !/^(?:con|prn|aux|nul|com[0-9]|lpt[0-9])(?:\.|$)/i.test(part)));
+}
+function manifest(files) {
+    return files.map(({ path, data, executable }) => ({
+        path,
+        size: data.length,
+        sha256: createHash('sha256').update(data).digest('hex'),
+        ...(executable ? { executable: true } : {}),
+    }));
+}
+function sameFiles(left, right) {
+    return isDeepStrictEqual(new Map(left.map((file) => [file.path, file])), new Map(right.map((file) => [file.path, file])));
+}
+async function readSource(source, signal) {
+    const build = { ...source.build, command: source.build.command.trim() };
+    const directory = await realpath(source.directory);
+    const files = await readDirectory(directory, (files) => validSource({ files, build }), signal, new SourceFileSelection(directory, build.outputDirectory, signal));
+    return { files, value: { files: manifest(files), build } };
+}
+/** Save a shared source checkpoint without compiling or publishing. */
+export async function saveAppSource(client, options, requestOptions) {
+    const input = structuredClone(options);
+    const source = await readSource(input.source, requestOptions?.signal);
+    await client.apps.uploadFiles(input.appId, source.files, requestOptions);
+    return client.apps.saveSite(input.appId, { source: source.value, expectedDraft: input.expectedDraft }, requestOptions);
+}
+/** Materialize the draft or an exact historical source revision into a new folder. Never overwrites files. */
+export async function checkoutApp(client, options, requestOptions) {
+    const { appId, directory, revisionId: selected } = structuredClone(options);
+    const history = await client.revisions.list(appId, requestOptions);
+    const revisionId = selected ?? history.draft?.revisionId;
+    if (!revisionId)
+        throw new Error('App has no draft.');
+    const revision = await client.revisions.get(appId, revisionId, requestOptions);
+    const source = revision.value.source;
+    if (!validSource(source))
+        throw new Error('This app revision has no valid stored source.');
+    const destination = resolve(directory);
+    const root = join(await realpath(dirname(destination)), basename(destination));
+    await mkdir(root); // Exclusive creation refuses existing folders, files, and symlinks.
+    for (const file of source.files) {
+        requestOptions?.signal?.throwIfAborted();
+        const content = await client.apps.sourceFile(appId, { revisionId, path: file.path }, requestOptions);
+        const bytes = Buffer.from(content.data, 'base64');
+        if (bytes.length !== file.size || createHash('sha256').update(bytes).digest('hex') !== file.sha256)
+            throw new Error(`Source file failed integrity verification: ${file.path}`);
+        const target = join(root, file.path);
+        await mkdir(dirname(target), { recursive: true });
+        await writeFile(target, bytes, { flag: 'wx', mode: file.executable ? 0o755 : 0o644 });
+    }
+    return { revisionId, source, expectedDraft: revisionId === history.draft?.revisionId ? history.draft : null };
+}
 /** Upload, save, and publish an existing live app. Builds and provisions nothing; never retries mutations. */
 export async function deployApp(client, options, requestOptions) {
-    const { appId, directory, spa = true, ...bindings } = structuredClone(options);
+    const { appId, directory, source: sourceOptions, spa = true, ...bindings } = structuredClone(options);
     const app = await client.apps.get(appId, requestOptions);
     if (app.deployment?.status !== 'live')
         throw new Error('App hosting must be live before deploying. Inspect client.apps.get(appId).');
     const history = await client.revisions.list(appId, requestOptions);
-    const expected = bindings.expectedDraft ?? app.draft;
+    const expected = bindings.expectedDraft;
+    if (!expected)
+        throw new Error('expectedDraft is required. Use the token from checkout or a reviewed app draft.');
     if (history.draft?.revisionId !== expected.revisionId ||
         history.draft.sequence !== expected.sequence ||
         app.draft.revisionId !== expected.revisionId ||
         app.draft.sequence !== expected.sequence) {
         conflict('App draft changed. Read and review it before deploying.');
     }
-    if (!bindings.expectedDraft && history.draft.revisionId !== history.published?.revisionId) {
-        conflict('App has an unpublished draft. Review it and supply its expectedDraft to replace it.');
-    }
-    const body = { ...bindings, expectedDraft: expected };
-    const files = await readBuild(directory, body, spa, requestOptions?.signal);
+    const source = await readSource(sourceOptions, requestOptions?.signal);
+    const body = { ...bindings, source: source.value, expectedDraft: expected };
+    const files = await readDirectory(directory, (files) => files.some((file) => file.path === 'index.html') &&
+        new Set(body.actions?.map((action) => action.actionId)).size === (body.actions?.length ?? 0) &&
+        validateSite({ ...body, site: { files, spa } }), requestOptions?.signal);
     // Only a clean published draft can be skipped: an approved draft may also contain settings edits.
     if (history.published && history.draft.revisionId === history.published.revisionId) {
         const revision = await client.revisions.get(appId, history.published.revisionId, requestOptions);
         const previous = {
             expectedDraft: expected,
-            site: revision.value.site,
+            source: revision.value.source,
+            site: revision.value.site && typeof revision.value.site === 'object'
+                ? Object.fromEntries(Object.entries(revision.value.site).filter(([key]) => key !== 'sourceHash'))
+                : revision.value.site,
             actions: revision.value.actions,
         };
-        const localManifest = files.map(({ path, data }) => ({
-            path,
-            size: data.length,
-            sha256: createHash('sha256').update(data).digest('hex'),
-        }));
+        const localManifest = manifest(files);
         if (validateSite(previous) &&
+            isDeepStrictEqual(previous.source.build, source.value.build) &&
+            sameFiles(previous.source.files, source.value.files) &&
+            previous.site &&
             previous.site.spa === spa &&
-            isDeepStrictEqual(new Map(previous.site.files.map((file) => [file.path, file])), new Map(localManifest.map((file) => [file.path, file]))) &&
+            sameFiles(previous.site.files, localManifest) &&
             (bindings.actions === undefined ||
                 isDeepStrictEqual(new Map((previous.actions ?? []).map((action) => [action.actionId, action.revisionId])), new Map(bindings.actions.map((action) => [action.actionId, action.revisionId]))))) {
             const current = await client.revisions.list(appId, requestOptions);
@@ -123,8 +200,9 @@ export async function deployApp(client, options, requestOptions) {
             return { url: app.deployment.url, revisionId: history.published.revisionId, changed: false };
         }
     }
-    const manifest = await client.apps.uploadFiles(appId, files, requestOptions);
-    const saved = await client.apps.saveSite(appId, { ...body, site: { files: manifest, spa } }, requestOptions);
+    await client.apps.uploadFiles(appId, source.files, requestOptions);
+    const siteFiles = await client.apps.uploadFiles(appId, files, requestOptions);
+    const saved = await client.apps.saveSite(appId, { ...body, site: { files: siteFiles, spa } }, requestOptions);
     const ready = await client.revisions.list(appId, requestOptions);
     if (ready.draft?.revisionId !== saved.draft.revisionId ||
         ready.draft.sequence !== saved.draft.sequence ||