@sequenceholdings/artifact-studio 0.1.5 → 0.1.9

package/dist/config.d.ts

@@ -13,6 +13,7 @@ export interface TokenConfig {
 export declare function globalConfigDir(): string;
 export declare function tokenConfigPath(): string;
 export declare function localConfigPath(cwd?: string): string;
+export declare function devLockPath(cwd?: string): string;
 export declare function readLocalConfig(cwd?: string): Promise<LocalProjectConfig>;
 export declare function writeLocalConfig(config: LocalProjectConfig, cwd?: string): Promise<void>;
 export declare function readTokenConfig(): Promise<TokenConfig>;

package/dist/config.js

@@ -17,6 +17,9 @@ export function tokenConfigPath() {
 export function localConfigPath(cwd = process.cwd()) {
     return join(resolve(cwd), '.artifact-studio', 'config.json');
 }
+export function devLockPath(cwd = process.cwd()) {
+    return join(resolve(cwd), '.artifact-studio', 'dev.lock');
+}
 export async function readLocalConfig(cwd = process.cwd()) {
     const path = localConfigPath(cwd);
     if (!existsSync(path))
@@ -41,7 +44,7 @@ export async function writeTokenConfig(config) {
 }
 export function resolveEnvironment(name, fallback) {
     const envName = name ?? fallback;
-    // Allow `seq-lattice artifact` (and any other embedder that wants to
+    // Allow `seq-studio artifact` (and any other embedder that wants to
     // route artifact-studio through a centrally-managed env map) to
     // override the base URL without monkey-patching this file. The env
     // name remains the user-supplied one so log lines / project records

package/dist/dev-link.d.ts

@@ -0,0 +1,60 @@
+/**
+ * `seq-studio artifact dev --link <pkgDir>` support.
+ *
+ * Artifacts consume shared libraries (notably `@sequenceholdings/atlas-ui`) as a
+ * prebuilt `dist` bundle, resolved from the artifact's `node_modules`. That makes
+ * editing a shared component a 4-step manual dance: rebuild the lib, force a
+ * reinstall so the new `dist` lands in the artifact's `node_modules`, restart the
+ * watcher (its source hash only covers artifact files, not deps), and refresh.
+ *
+ * `--link` collapses that to zero steps: the watcher hashes the linked package's
+ * source each tick, and on change rebuilds the package and copies its fresh `dist`
+ * into the exact location the artifact build resolves it from — then forces an
+ * artifact rebuild + preview push.
+ */
+export interface LinkedDep {
+    /** Absolute path to the linked source package (e.g. shared/services/atlas-ui). */
+    dir: string;
+    /** Package name from its package.json (e.g. @sequenceholdings/atlas-ui). */
+    name: string;
+    /** Absolute path to the package's source dir, watched for changes. */
+    srcDir: string;
+    /** Absolute path to the package's dist dir, produced by its build script. */
+    distDir: string;
+    /** Absolute path to the dist dir the artifact build actually resolves from. */
+    targetDistDir: string;
+    /** True when the artifact resolves the package straight from `dir` (symlinked file: dep). */
+    inPlace: boolean;
+}
+/** Resolve `${name}/package.json` the same way the build worker does. */
+type PackageResolver = (request: string) => string;
+/** Split a `--link a,b` flag value into trimmed, non-empty paths. */
+export declare function parseLinks(flag: string | true | undefined): string[];
+/**
+ * Turn `--link` paths into resolved link descriptors. Each path is resolved
+ * relative to `cwd` (where the user invoked the CLI). The artifact's installed
+ * copy of the package is located via the same module resolution the build uses,
+ * so the copied `dist` lands exactly where the build will read it.
+ */
+export declare function resolveLinkedDeps({ links, cwd, resolver, readPackageName, }: {
+    links: string[];
+    cwd?: string;
+    resolver?: PackageResolver;
+    readPackageName?: (pkgDir: string) => string;
+}): LinkedDep[];
+/**
+ * Content-hash the watched source of every linked package. The watcher compares
+ * this between ticks to decide whether a linked package changed and must be
+ * rebuilt — analogous to the artifact's own source hash.
+ */
+export declare function hashLinkedSources(deps: readonly LinkedDep[]): Promise<string>;
+/** Run a linked package's `build` script in a child process. */
+export declare function rebuildLinkedDep(dep: LinkedDep, signal?: AbortSignal): Promise<void>;
+/**
+ * Copy a linked package's freshly built `dist` into the location the artifact
+ * build resolves it from. A no-op when the artifact already resolves the package
+ * in place (symlinked file: dep), where the rebuild already wrote the bytes the
+ * build will read.
+ */
+export declare function syncLinkedDist(dep: LinkedDep): Promise<void>;
+export {};

package/dist/dev-link.js

@@ -0,0 +1,155 @@
+import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { cp, readFile, readdir, rm } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { dirname, join, relative, resolve } from 'node:path';
+const WATCHED_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx', '.css', '.json']);
+const IGNORED_DIRS = new Set(['node_modules', '.git', 'dist', '.next', '.turbo', '.cache']);
+const defaultResolver = createRequire(import.meta.url).resolve;
+/** Split a `--link a,b` flag value into trimmed, non-empty paths. */
+export function parseLinks(flag) {
+    if (typeof flag !== 'string')
+        return [];
+    return flag
+        .split(',')
+        .map((entry) => entry.trim())
+        .filter(Boolean);
+}
+/**
+ * Turn `--link` paths into resolved link descriptors. Each path is resolved
+ * relative to `cwd` (where the user invoked the CLI). The artifact's installed
+ * copy of the package is located via the same module resolution the build uses,
+ * so the copied `dist` lands exactly where the build will read it.
+ */
+export function resolveLinkedDeps({ links, cwd = process.cwd(), resolver = defaultResolver, readPackageName = defaultReadPackageName, }) {
+    return links.map((link) => {
+        const dir = resolve(cwd, link);
+        if (!existsSync(dir))
+            throw new Error(`--link path does not exist: ${dir}`);
+        const name = readPackageName(dir);
+        let targetPkgDir;
+        try {
+            targetPkgDir = dirname(resolver(`${name}/package.json`));
+        }
+        catch {
+            throw new Error(`Cannot resolve "${name}" from the artifact — is it listed as a dependency? (--link ${link})`);
+        }
+        return {
+            dir,
+            name,
+            srcDir: join(dir, 'src'),
+            distDir: join(dir, 'dist'),
+            targetDistDir: join(targetPkgDir, 'dist'),
+            inPlace: samePath(targetPkgDir, dir),
+        };
+    });
+}
+function defaultReadPackageName(pkgDir) {
+    const pkgJsonPath = join(pkgDir, 'package.json');
+    if (!existsSync(pkgJsonPath))
+        throw new Error(`No package.json found at ${pkgJsonPath}`);
+    const parsed = JSON.parse(readFileSync(pkgJsonPath, 'utf8'));
+    if (!parsed.name)
+        throw new Error(`package.json at ${pkgJsonPath} has no "name"`);
+    return parsed.name;
+}
+function samePath(a, b) {
+    try {
+        return realpathSync(a) === realpathSync(b);
+    }
+    catch {
+        return resolve(a) === resolve(b);
+    }
+}
+/**
+ * Content-hash the watched source of every linked package. The watcher compares
+ * this between ticks to decide whether a linked package changed and must be
+ * rebuilt — analogous to the artifact's own source hash.
+ */
+export async function hashLinkedSources(deps) {
+    const hash = createHash('sha256');
+    for (const dep of deps) {
+        hash.update(dep.name);
+        hash.update('\0');
+        const files = (await collectFiles(dep.srcDir)).sort((a, b) => a.localeCompare(b));
+        for (const file of files) {
+            hash.update(relative(dep.srcDir, file));
+            hash.update('\0');
+            hash.update(await readFile(file));
+            hash.update('\0');
+        }
+    }
+    return hash.digest('hex');
+}
+async function collectFiles(root) {
+    if (!existsSync(root))
+        return [];
+    const out = [];
+    async function walk(dir) {
+        const entries = await readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const absolute = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (!IGNORED_DIRS.has(entry.name))
+                    await walk(absolute);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            const ext = entry.name.includes('.') ? entry.name.slice(entry.name.lastIndexOf('.')) : '';
+            if (WATCHED_EXTENSIONS.has(ext))
+                out.push(absolute);
+        }
+    }
+    await walk(root);
+    return out;
+}
+/** Run a linked package's `build` script in a child process. */
+export function rebuildLinkedDep(dep, signal) {
+    return new Promise((resolveBuild, reject) => {
+        if (signal?.aborted) {
+            reject(new Error('build aborted'));
+            return;
+        }
+        const child = spawn('pnpm', ['run', 'build'], {
+            cwd: dep.dir,
+            stdio: ['ignore', 'inherit', 'inherit'],
+        });
+        const onAbort = () => {
+            child.kill('SIGTERM');
+        };
+        signal?.addEventListener('abort', onAbort, { once: true });
+        child.on('error', (error) => {
+            signal?.removeEventListener('abort', onAbort);
+            reject(error);
+        });
+        child.on('close', (code) => {
+            signal?.removeEventListener('abort', onAbort);
+            if (signal?.aborted) {
+                reject(new Error('build aborted'));
+                return;
+            }
+            if (code === 0) {
+                resolveBuild();
+                return;
+            }
+            reject(new Error(`${dep.name} build exited with code ${code ?? 'null'}`));
+        });
+    });
+}
+/**
+ * Copy a linked package's freshly built `dist` into the location the artifact
+ * build resolves it from. A no-op when the artifact already resolves the package
+ * in place (symlinked file: dep), where the rebuild already wrote the bytes the
+ * build will read.
+ */
+export async function syncLinkedDist(dep) {
+    if (dep.inPlace)
+        return;
+    if (!existsSync(dep.distDir)) {
+        throw new Error(`${dep.name} build produced no dist at ${dep.distDir}`);
+    }
+    await rm(dep.targetDistDir, { recursive: true, force: true });
+    await cp(dep.distDir, dep.targetDistDir, { recursive: true });
+}

package/dist/dev-lock.d.ts

@@ -0,0 +1,5 @@
+export declare function acquireDevLock({ dir, previewKey, log, }: {
+    dir: string;
+    previewKey?: string;
+    log?: (message: string) => void;
+}): Promise<() => void>;

package/dist/dev-lock.js

@@ -0,0 +1,83 @@
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { dirname } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { devLockPath } from './config.js';
+function isProcessAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        // Signal 0 performs existence/permission checks without delivering a signal.
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // EPERM means the process exists but is owned by another user — still alive.
+        return error.code === 'EPERM';
+    }
+}
+function readDevLock(path) {
+    if (!existsSync(path))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        return typeof parsed?.pid === 'number' ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function waitForExit(pid, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (!isProcessAlive(pid))
+            return;
+        await delay(100);
+    }
+    // Last resort: a watcher that ignored SIGTERM gets force-killed so it can't
+    // keep racing on the token file.
+    if (isProcessAlive(pid)) {
+        try {
+            process.kill(pid, 'SIGKILL');
+        }
+        catch {
+            // Raced to exit between the check and the kill — already gone.
+        }
+    }
+}
+export async function acquireDevLock({ dir, previewKey, log = console.log, }) {
+    const path = devLockPath(dir);
+    const existing = readDevLock(path);
+    if (existing && existing.pid !== process.pid && isProcessAlive(existing.pid)) {
+        log(`[seq-studio] stopping previous dev watcher (pid ${existing.pid})`);
+        try {
+            process.kill(existing.pid, 'SIGTERM');
+        }
+        catch {
+            // Exited between read and kill — nothing to stop.
+        }
+        await waitForExit(existing.pid, 3000);
+    }
+    mkdirSync(dirname(path), { recursive: true });
+    const lock = {
+        pid: process.pid,
+        startedAt: new Date().toISOString(),
+        ...(previewKey ? { previewKey } : {}),
+    };
+    writeFileSync(path, JSON.stringify(lock, null, 2), 'utf8');
+    let released = false;
+    return () => {
+        if (released)
+            return;
+        released = true;
+        try {
+            // Only remove the lock if it's still ours — a newer watcher may have
+            // already taken over and we must not delete its lock.
+            const current = readDevLock(path);
+            if (current?.pid === process.pid)
+                unlinkSync(path);
+        }
+        catch {
+            // Best-effort cleanup; never throw from a shutdown path.
+        }
+    };
+}

package/dist/git-clone.d.ts

@@ -0,0 +1,41 @@
+/** Read the git PAT from the environment (`ATLAS_GIT_PAT`), trimmed. */
+export declare function resolveGitPatFromEnv(): string | undefined;
+/** Full or abbreviated hex SHAs — not valid as `git clone --branch`. */
+export declare function looksLikeCommitSha(ref: string): boolean;
+/**
+ * Smart-HTTP clone base for a git-service repo id (aligned with PLA-83:
+ * `<origin>/api/git-service/repos/<id>/git`). Git appends `/info/refs` and
+ * `/git-upload-pack` itself.
+ */
+export declare function gitServiceCloneUrl(baseUrl: string, repoId: string): string;
+export declare function redactCloneUrl(url: string): string;
+export type RunGitClone = (args: {
+    /** Clean HTTPS clone URL — no embedded credentials. */
+    cloneUrl: string;
+    destDir: string;
+    /** Optional branch, tag, or commit SHA. */
+    ref?: string;
+    /** PAT used as Basic-auth password (username `git`). */
+    pat: string;
+    /** Hard ceiling before the git child is killed (default 5m). */
+    timeoutMs?: number;
+}) => Promise<void>;
+/**
+ * Run `fn` with GIT_ASKPASS set to a short-lived script that answers username
+ * with `git` and password with `pat`. The script is deleted afterward.
+ */
+export declare function withGitAskpass<T>({ pat, fn, }: {
+    pat: string;
+    fn: (env: NodeJS.ProcessEnv) => Promise<T>;
+}): Promise<T>;
+/**
+ * Clone with a clean URL + PAT via askpass. Branch/tag refs use `--branch`;
+ * commit SHAs clone default HEAD then `git checkout <sha>`.
+ */
+export declare function runGitClone({ cloneUrl, destDir, ref, pat, timeoutMs, }: {
+    cloneUrl: string;
+    destDir: string;
+    ref?: string;
+    pat: string;
+    timeoutMs?: number;
+}): Promise<void>;

package/dist/git-clone.js

@@ -0,0 +1,178 @@
+/**
+ * Smart-HTTP git clone helpers for the platform git-service.
+ *
+ * This is the canonical implementation. `@sequenceholdings/studio-cli`
+ * re-exports it from `src/repos/git-clone.ts` so the `repos` tool and the
+ * artifact `--repo` deploy path share one clone path.
+ *
+ * Credentials are supplied via an ephemeral GIT_ASKPASS script so the PAT
+ * never lands in `remote.origin.url` or the git argv. Callers pass a clean
+ * HTTPS clone URL plus the PAT separately.
+ */
+import { spawn } from 'node:child_process';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+/** Read the git PAT from the environment (`ATLAS_GIT_PAT`), trimmed. */
+export function resolveGitPatFromEnv() {
+    const value = process.env.ATLAS_GIT_PAT?.trim();
+    return value || undefined;
+}
+/** Full or abbreviated hex SHAs — not valid as `git clone --branch`. */
+export function looksLikeCommitSha(ref) {
+    return /^[0-9a-f]{7,40}$/i.test(ref);
+}
+/**
+ * Smart-HTTP clone base for a git-service repo id (aligned with PLA-83:
+ * `<origin>/api/git-service/repos/<id>/git`). Git appends `/info/refs` and
+ * `/git-upload-pack` itself.
+ */
+export function gitServiceCloneUrl(baseUrl, repoId) {
+    return `${baseUrl.replace(/\/+$/, '')}/api/git-service/repos/${repoId}/git`;
+}
+export function redactCloneUrl(url) {
+    try {
+        const parsed = new URL(url);
+        if (parsed.password)
+            parsed.password = '***';
+        return parsed.toString();
+    }
+    catch {
+        return url.replace(/:[^/@]+@/, ':***@');
+    }
+}
+/**
+ * Abort an HTTP transfer that drops below ~1 KB/s for 30s — the primary stall
+ * guard, so a wedged smart-HTTP fetch fails cleanly in ~30s instead of hanging
+ * a deploy/CI. Passed as `git -c` so it applies to the clone's fetch.
+ */
+const GIT_LOW_SPEED_LIMIT_BYTES = 1000;
+const GIT_LOW_SPEED_TIME_SEC = 30;
+/** Backstop hard deadline: kill the child even if it trickles just above the low-speed floor. */
+const GIT_CLONE_TIMEOUT_MS = 5 * 60_000;
+/** First non-flag arg (the git subcommand), skipping `-c <value>` config pairs. */
+function gitVerb(args) {
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === '-c') {
+            i += 1; // skip the config value that follows -c
+            continue;
+        }
+        if (!a.startsWith('-'))
+            return a;
+    }
+    return 'git';
+}
+async function spawnGit({ args, env, cwd, timeoutMs = GIT_CLONE_TIMEOUT_MS, }) {
+    const verb = gitVerb(args);
+    await new Promise((resolve, reject) => {
+        const child = spawn('git', args, {
+            cwd,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            env,
+        });
+        let stderr = '';
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill('SIGKILL');
+        }, timeoutMs);
+        child.stderr?.on('data', (chunk) => {
+            stderr += chunk.toString();
+        });
+        child.on('error', (err) => {
+            clearTimeout(timer);
+            reject(err);
+        });
+        child.on('close', (code) => {
+            clearTimeout(timer);
+            if (timedOut) {
+                reject(new Error(`git ${verb} exceeded ${Math.round(timeoutMs / 1000)}s and was terminated (transport stalled)`));
+                return;
+            }
+            if (code === 0) {
+                resolve();
+                return;
+            }
+            reject(new Error(`git ${verb} failed (exit ${code ?? 'null'}): ${stderr.trim() || 'no stderr'}`));
+        });
+    });
+}
+/**
+ * Run `fn` with GIT_ASKPASS set to a short-lived script that answers username
+ * with `git` and password with `pat`. The script is deleted afterward.
+ */
+export async function withGitAskpass({ pat, fn, }) {
+    const dir = await mkdtemp(join(tmpdir(), 'artifact-askpass-'));
+    const scriptPath = join(dir, 'askpass.sh');
+    const script = [
+        '#!/bin/sh',
+        'case "$1" in',
+        "  *[Uu]sername*) printf '%s\\n' git ;;",
+        '  *) printf \'%s\\n\' "$SEQ_STUDIO_GIT_ASKPASS_PASSWORD" ;;',
+        'esac',
+        '',
+    ].join('\n');
+    await writeFile(scriptPath, script, { mode: 0o700 });
+    try {
+        return await fn({
+            ...process.env,
+            GIT_ASKPASS: scriptPath,
+            GIT_TERMINAL_PROMPT: '0',
+            SEQ_STUDIO_GIT_ASKPASS_PASSWORD: pat,
+            GIT_CONFIG_COUNT: '1',
+            GIT_CONFIG_KEY_0: 'credential.helper',
+            GIT_CONFIG_VALUE_0: '',
+        });
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+}
+/**
+ * Clone with a clean URL + PAT via askpass. Branch/tag refs use `--branch`;
+ * commit SHAs clone default HEAD then `git checkout <sha>`.
+ */
+export async function runGitClone({ cloneUrl, destDir, ref, pat, timeoutMs, }) {
+    let cleanUrl = cloneUrl;
+    try {
+        const parsed = new URL(cloneUrl);
+        if (parsed.username || parsed.password) {
+            parsed.username = '';
+            parsed.password = '';
+            cleanUrl = parsed.toString();
+        }
+    }
+    catch {
+        // leave as-is; git will fail loudly
+    }
+    // Global `-c` config must precede the subcommand. Low-speed settings bound
+    // the fetch so a stalled transport aborts fast rather than wedging the deploy.
+    const lowSpeed = [
+        '-c',
+        `http.lowSpeedLimit=${GIT_LOW_SPEED_LIMIT_BYTES}`,
+        '-c',
+        `http.lowSpeedTime=${GIT_LOW_SPEED_TIME_SEC}`,
+    ];
+    await withGitAskpass({
+        pat,
+        fn: async (env) => {
+            const args = [...lowSpeed, 'clone'];
+            const shaRef = ref && looksLikeCommitSha(ref) ? ref : undefined;
+            const branchRef = ref && !shaRef ? ref : undefined;
+            if (branchRef)
+                args.push('--branch', branchRef);
+            args.push(cleanUrl, destDir);
+            try {
+                await spawnGit({ args, env, ...(timeoutMs ? { timeoutMs } : {}) });
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                throw new Error(`${message}\n  url: ${redactCloneUrl(cleanUrl)}`);
+            }
+            if (shaRef) {
+                await spawnGit({ args: ['checkout', '--detach', shaRef], env, cwd: destDir, ...(timeoutMs ? { timeoutMs } : {}) });
+            }
+        },
+    });
+}

package/dist/git-service-client.d.ts

@@ -0,0 +1,32 @@
+/** Resolve `namespace/name` to a repo id + default branch (FGA-filtered list, paginated). */
+export declare function resolveRepo({ baseUrl, token, namespace, name, }: {
+    baseUrl: string;
+    token: string;
+    namespace: string;
+    name: string;
+}): Promise<{
+    id: string;
+    defaultBranch: string;
+}>;
+/**
+ * Resolve a ref (branch, tag, short name, or 40-hex SHA) to its commit SHA.
+ * Tries the refs endpoint first (cheap), then commit detail (which also
+ * verifies a raw SHA points at a real commit).
+ */
+export declare function resolveCommitSha({ baseUrl, token, repoId, ref, }: {
+    baseUrl: string;
+    token: string;
+    repoId: string;
+    ref: string;
+}): Promise<string>;
+/**
+ * Materialize the full tree at `ref` into `destDir` (recursive tree listing +
+ * one content fetch per blob). Returns the number of files written.
+ */
+export declare function materializeRepo({ baseUrl, token, repoId, ref, destDir, }: {
+    baseUrl: string;
+    token: string;
+    repoId: string;
+    ref: string;
+    destDir: string;
+}): Promise<number>;