@shardflux/cli 0.11.0 → 0.13.0

package/dist/git-remote.js

@@ -0,0 +1,136 @@
+import { once } from 'node:events';
+import { UsageError } from "./errors.js";
+/** Keys have two segments (K9). Everything after the agent is an absolute guest path. */
+export function parseShardRemote(url) {
+    const match = /^shard:\/\/([^/?#]+)\/([^/?#]+)\/(.+)$/.exec(url);
+    if (!match)
+        throw new UsageError('expected shard://<project>/<agent>/<absolute guest path>');
+    const key = `${decodeURIComponent(match[1])}/${decodeURIComponent(match[2])}`;
+    const path = `/${decodeURIComponent(match[3])}`;
+    if (!/^[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]{0,63}$/.test(key) || [...path].some(ch => ch.charCodeAt(0) < 32 || ch.charCodeAt(0) === 127))
+        throw new UsageError('invalid shard workspace key or repository path');
+    return { key, path };
+}
+export function shardRemote(key, path) {
+    if (!path.startsWith('/'))
+        throw new UsageError('remote repository path must be absolute');
+    const url = `shard://${key}/${path.slice(1).split('/').map(encodeURIComponent).join('/')}`;
+    parseShardRemote(url);
+    return url;
+}
+async function write(stream, bytes) {
+    if (!stream.write(bytes))
+        await once(stream, 'drain');
+}
+/** No text decoding of the pack stream; offsets are acknowledged bytes, including partial stdin writes. */
+export async function bridgeGit(exec, service, path, input, stdout, stderr, signal) {
+    if (service !== 'git-upload-pack' && service !== 'git-receive-pack')
+        throw new UsageError('unsupported Git service');
+    const controller = new AbortController();
+    const combined = AbortSignal.any([signal, controller.signal]);
+    const session = await exec.start({ argv: [service, path], stdin_open: true, timeout_ms: 600_000 }, combined);
+    let ended = false, offset = 0;
+    const send = async () => {
+        for await (const chunk of input) {
+            for (let at = 0; at < chunk.length;) {
+                combined.throwIfAborted();
+                const frame = chunk.subarray(at, at + 65_536);
+                const ack = await exec.input(session.session_id, frame, { offset, signal: combined });
+                const accepted = ack.offset - offset;
+                if (!Number.isSafeInteger(accepted) || accepted <= 0 || accepted > frame.length || ack.closed)
+                    throw new Error('Git stdin returned an invalid acknowledgement');
+                offset = ack.offset;
+                at += accepted;
+            }
+        }
+        if (!ended) {
+            const ack = await exec.input(session.session_id, new Uint8Array(), { offset, close: true, signal: combined });
+            if (ack.offset !== offset || !ack.closed)
+                throw new Error('Git stdin did not acknowledge EOF');
+        }
+    };
+    const receive = async () => {
+        const offsets = { stdout: 0, stderr: 0 };
+        const events = await exec.output(session.session_id, { follow: true, signal: combined });
+        for await (const event of events) {
+            if (event.type === 'output') {
+                if (!event.stream || event.offset === undefined || event.data === undefined)
+                    throw new Error('Git output omitted its stream or byte offset');
+                const bytes = Buffer.from(event.data, 'base64');
+                const expected = offsets[event.stream];
+                if (event.offset > expected)
+                    throw new Error('Git output has a byte gap');
+                const fresh = bytes.subarray(Math.max(0, expected - event.offset));
+                if (fresh.length)
+                    await write(event.stream === 'stdout' ? stdout : stderr, fresh);
+                offsets[event.stream] = Math.max(expected, event.offset + bytes.length);
+            }
+            else if (event.type === 'error')
+                throw new Error(`Git exec output failed: ${event.error?.error.message ?? 'stream error'}`);
+            else if (event.type === 'exit') {
+                ended = true;
+                if (!event.session || offsets.stdout !== event.session.stdout_size || offsets.stderr !== event.session.stderr_size)
+                    throw new Error('Git exec ended before all output arrived');
+                return event.session.exit_code ?? 1;
+            }
+        }
+        throw new Error('Git exec output ended without an exit event');
+    };
+    // Observe both promises immediately. Git may exit without closing its input pipe on a failed negotiation.
+    const sending = send();
+    const receiving = receive();
+    try {
+        const code = await Promise.race([receiving, sending.then(() => receiving)]);
+        return code;
+    }
+    finally {
+        controller.abort();
+        if (!ended)
+            await exec.cancel(session.session_id, 1000).catch(() => undefined);
+        void sending.catch(() => undefined);
+    }
+}
+/** Git's `connect` capability switches from newline commands to a full-duplex smart protocol. */
+export async function remoteHelper(url, stdin, stdout, stderr, connect, signal) {
+    const remote = parseShardRemote(url);
+    const iterator = stdin[Symbol.asyncIterator]();
+    let pending = Buffer.alloc(0);
+    while (true) {
+        let newline = pending.indexOf(10);
+        while (newline < 0) {
+            const next = await iterator.next();
+            if (next.done)
+                return pending.length ? 1 : 0;
+            pending = Buffer.concat([pending, Buffer.from(next.value)]);
+            newline = pending.indexOf(10);
+            if (newline > 4096 || newline < 0 && pending.length > 4096)
+                throw new UsageError('Git helper command is too long');
+        }
+        const command = pending.subarray(0, newline).toString('utf8');
+        pending = pending.subarray(newline + 1);
+        if (command === '')
+            return 0;
+        if (command === 'capabilities')
+            await write(stdout, 'connect\n\n');
+        else if (command.startsWith('connect ')) {
+            const service = command.slice(8);
+            if (!['git-upload-pack', 'git-receive-pack'].includes(service))
+                throw new UsageError('unsupported Git service');
+            const exec = await connect(remote);
+            await write(stdout, '\n');
+            const input = { async *[Symbol.asyncIterator]() {
+                    if (pending.length)
+                        yield pending;
+                    while (true) {
+                        const next = await iterator.next();
+                        if (next.done)
+                            return;
+                        yield Buffer.from(next.value);
+                    }
+                } };
+            return bridgeGit(exec, service, remote.path, input, stdout, stderr, signal);
+        }
+        else
+            throw new UsageError(`unsupported Git helper command: ${command}`);
+    }
+}

package/dist/handlers.js

@@ -1,7 +1,15 @@
+import { CREDENTIAL_HANDLERS } from "./credential-prompts.js";
 /**
  * Every command's handler, keyed by its path ("workspaces open", "auth login"): the project-key commands of
  * commands.ts and the account plane of account-commands.ts (0.5.0). args.test.ts checks that it matches COMMANDS.
  */
+import { AGENT_CREDENTIAL_HANDLERS } from "./agent-credentials.js";
 import { ACCOUNT_HANDLERS } from "./account-commands.js";
 import { KEY_HANDLERS } from "./commands.js";
-export const HANDLERS = { ...KEY_HANDLERS, ...ACCOUNT_HANDLERS };
+import { AGENT_HANDLERS } from "./agent-commands.js";
+import { TARGET_HANDLERS } from "./agent-target-commands.js";
+import { CENTER_HANDLERS } from "./command-center-actions.js";
+import { AGENT_GIT_HANDLERS } from "./agent-git-commands.js";
+import { MENUBAR_HANDLERS } from "./menubar.js";
+import { FILESYSTEM_HANDLERS } from "./filesystem-commands.js";
+export const HANDLERS = { ...CREDENTIAL_HANDLERS, ...AGENT_CREDENTIAL_HANDLERS, ...KEY_HANDLERS, ...ACCOUNT_HANDLERS, ...AGENT_HANDLERS, ...CENTER_HANDLERS, ...TARGET_HANDLERS, ...AGENT_GIT_HANDLERS, ...MENUBAR_HANDLERS, ...FILESYSTEM_HANDLERS };

package/dist/index.d.ts

@@ -23,3 +23,5 @@ export { EXIT, AuthConfigError, CheckoutEndedError, ExecutionFailedError, Execut
 export type { ErrorInfo } from './errors.js';
 export { changedText, errorText, executionJson, executionSummary, feedbackCommand, json, suspendRequestText, suspendWhenIdleText, table, time, usageText, workspaceDetail, workspaceTable } from './format.js';
 export { TimingRecorder, coldBootNotice, hostLostNotice, lostSuspendNotice, notices, timingJson, timingText } from './timing.js';
+export { readAgentCredentials, syncAgentCredentials } from './agent-credentials.js';
+export type { CredentialSources } from './agent-credentials.js';

package/dist/index.js

@@ -15,3 +15,4 @@ export { openUrl, openerFor } from "./browser.js";
 export { EXIT, AuthConfigError, CheckoutEndedError, ExecutionFailedError, ExecutionPendingError, InterruptedError, MfaPendingError, NotFoundError, UsageError, describeError, exitCodeFor, redact } from "./errors.js";
 export { changedText, errorText, executionJson, executionSummary, feedbackCommand, json, suspendRequestText, suspendWhenIdleText, table, time, usageText, workspaceDetail, workspaceTable } from "./format.js";
 export { TimingRecorder, coldBootNotice, hostLostNotice, lostSuspendNotice, notices, timingJson, timingText } from "./timing.js";
+export { readAgentCredentials, syncAgentCredentials } from "./agent-credentials.js";

package/dist/input.d.ts

@@ -1,5 +1,10 @@
 export interface StdinLike extends AsyncIterable<Buffer | string> {
     isTTY?: boolean;
+    isRaw?: boolean;
+    on?: (event: string, listener: (value: Buffer | string) => void) => unknown;
+    off?: (event: string, listener: (value: Buffer | string) => void) => unknown;
+    resume?: () => unknown;
+    pause?: () => unknown;
     /** tty.ReadStream#setRawMode: needed to read a secret on a terminal without echoing it. */
     setRawMode?: (raw: boolean) => unknown;
 }

package/dist/main.js

@@ -11,8 +11,11 @@
  * Every credential the command loaded is redacted from what it prints on failure.
  */
 import { hostname } from 'node:os';
+import { statSync } from 'node:fs';
 import { SDK_VERSION, Shardflux, ShardfluxAccount, isSessionToken } from '@shardflux/sdk';
-import { CLI_VERSION, parseCommandLine, resolveApiUrl, resolveWake, resolveWakeTimeout } from "./args.js";
+import { CLI_VERSION, CENTER_COMMAND, PROJECT_COMMAND, commandHelp, parseCommandLine, resolveApiUrl, resolveWake, resolveWakeTimeout } from "./args.js";
+import { commandCenter } from "./command-center.js";
+import { housekeeping, startupHousekeeping } from "./agent-git-commands.js";
 import { CredentialStore, configDir } from "./credentials.js";
 import { AuthConfigError, EXIT, ExecutionPendingError, InterruptedError, UsageError, describeError, exitCodeFor, ownHint, redact } from "./errors.js";
 import { errorText, feedbackCommand, json, time } from "./format.js";
@@ -398,19 +401,31 @@ export async function run(argv, io, opts = {}) {
     };
     let parsed;
     try {
-        parsed = parseCommandLine(argv);
+        parsed = parseCommandLine(argv, { tty: io.stdin.isTTY === true && io.stdout.isTTY !== false, isProjectPath: (path) => { try {
+                return statSync(path).isDirectory();
+            }
+            catch {
+                return false;
+            } } });
     }
     catch (err) {
         return report(err);
     }
     if (parsed.kind === 'help') {
+        await startupHousekeeping({ io, store, signal });
         io.stdout.write(parsed.text);
         return EXIT.ok;
     }
     if (parsed.kind === 'version') {
+        await startupHousekeeping({ io, store, signal });
         io.stdout.write(wantsJson ? json({ cli: CLI_VERSION, sdk: SDK_VERSION }) : `shard ${CLI_VERSION} (@shardflux/sdk ${SDK_VERSION})\n`);
         return EXIT.ok;
     }
+    if (parsed.command === PROJECT_COMMAND && (!io.stdin.isTTY || io.stdout.isTTY === false) && !parsed.global.json) {
+        await startupHousekeeping({ io, store, signal });
+        io.stdout.write(commandHelp(PROJECT_COMMAND));
+        return EXIT.ok;
+    }
     command = parsed.command.path.join(' ');
     let ctx;
     let updates = null;
@@ -590,7 +605,7 @@ export async function run(argv, io, opts = {}) {
             },
         };
         // The update check runs next to the command (not for `version`, which reports it itself).
-        if (!updateCheckDisabled(io.env) && parsed.command.path[0] !== 'version') {
+        if (!updateCheckDisabled(io.env) && !['version', 'ssh-proxy'].includes(parsed.command.path[0])) {
             try {
                 updates = new UpdateCheck({ dir: store.dir, apiUrl, distribution, fetch: base, userAgent });
                 updates.start();
@@ -603,13 +618,14 @@ export async function run(argv, io, opts = {}) {
     catch (err) {
         return report(err);
     }
-    const handler = HANDLERS[parsed.command.path.join(' ')];
+    const handler = parsed.command === PROJECT_COMMAND || parsed.command === CENTER_COMMAND ? commandCenter : HANDLERS[parsed.command.path.join(' ')];
     if (!handler)
         return report(new UsageError(`unknown command "${parsed.command.path.join(' ')}"`));
+    await housekeeping(ctx);
     const running = handler(ctx, parsed.values, parsed.positionals).then((code) => ({ code }), (err) => ({ err }));
     // On Ctrl-C give the command a moment to clean up (exec sends a cancel), then stop regardless.
     const interrupted = new Promise((resolve) => {
-        const cleanupMs = parsed.command.path.join(' ') === 'workspaces tunnel' ? 90_000 : 4_000;
+        const cleanupMs = ['workspaces tunnel', 'ssh-proxy'].includes(parsed.command.path.join(' ')) ? 90_000 : 4_000;
         const onAbort = () => setTimeout(() => resolve({ interrupted: true }), cleanupMs).unref();
         if (signal.aborted)
             onAbort();

package/dist/menubar.d.ts

@@ -0,0 +1,32 @@
+import type { Handler } from './commands.js';
+export type NativeRunner = (tool: string, args: string[]) => Promise<string>;
+export interface MenubarStatus {
+    installed: boolean;
+    version: string | null;
+    running: boolean;
+    pids: number[];
+    login: 'on' | 'off' | 'requires_approval' | 'not_found';
+}
+type NativeStatus = Omit<MenubarStatus, 'installed' | 'version'>;
+export declare function compareBundleVersions(left: string, right: string): number;
+export declare function parseNativeStatus(text: string): NativeStatus;
+/** Native tools use argument arrays, bounded deadlines, and the installed app's own process/login projection. */
+export declare class MenubarManager {
+    #private;
+    readonly app: string;
+    constructor(options?: {
+        home?: string;
+        platform?: NodeJS.Platform;
+        run?: NativeRunner;
+        packageApp?: () => string;
+        signal?: AbortSignal;
+    });
+    status(): Promise<MenubarStatus>;
+    stop(): Promise<MenubarStatus>;
+    login(value: 'on' | 'off'): Promise<MenubarStatus>;
+    start(configDir: string, apiUrl: string): Promise<MenubarStatus>;
+}
+/** Only the command center consumes this hint. It reads status, never resolves or installs the optional package. */
+export declare function menubarHint(dir: string, manager?: MenubarManager): Promise<string | undefined>;
+export declare const MENUBAR_HANDLERS: Record<string, Handler>;
+export {};

package/dist/menubar.js

@@ -0,0 +1,180 @@
+import { execFile } from 'node:child_process';
+import { cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, renameSync, rmSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { promisify } from 'node:util';
+import { AgentStateStore } from "./agent-state.js";
+import { UsageError } from "./errors.js";
+import { json } from "./format.js";
+const execute = promisify(execFile);
+const BUNDLE_ID = 'dev.shardflux.menubar';
+export function compareBundleVersions(left, right) {
+    if (![left, right].every(v => /^\d+(\.\d+){0,3}$/.test(v)))
+        throw new UsageError('Shardflux app has an invalid bundle version.');
+    const a = left.split('.').map(Number), b = right.split('.').map(Number);
+    for (let i = 0; i < Math.max(a.length, b.length); i++) {
+        if ((a[i] ?? 0) !== (b[i] ?? 0))
+            return (a[i] ?? 0) < (b[i] ?? 0) ? -1 : 1;
+    }
+    return 0;
+}
+export function parseNativeStatus(text) {
+    const value = JSON.parse(text);
+    if (!value || typeof value !== 'object')
+        throw new UsageError('Could not read Shardflux app status.');
+    const row = value;
+    if (typeof row.running !== 'boolean' || !Array.isArray(row.pids) || !row.pids.every(n => Number.isInteger(n) && n > 0) ||
+        !['on', 'off', 'requires_approval', 'not_found'].includes(String(row.login)) || row.running !== (row.pids.length > 0)) {
+        throw new UsageError('Could not read Shardflux app status.');
+    }
+    return row;
+}
+/** Native tools use argument arrays, bounded deadlines, and the installed app's own process/login projection. */
+export class MenubarManager {
+    app;
+    #run;
+    #platform;
+    #packageApp;
+    constructor(options = {}) {
+        this.app = join(options.home ?? homedir(), 'Applications', 'Shardflux.app');
+        this.#platform = options.platform ?? process.platform;
+        this.#run = options.run ?? (async (tool, args) => (await execute(tool, args, { timeout: 15000, maxBuffer: 1024 * 1024, signal: options.signal })).stdout);
+        this.#packageApp = options.packageApp ?? (() => {
+            try {
+                return join(dirname(createRequire(import.meta.url).resolve('@shardflux/menubar-darwin/package.json')), 'Shardflux.app');
+            }
+            catch {
+                throw new UsageError('The macOS app package is missing. Reinstall shard with optional dependencies enabled, then run shard menubar start.');
+            }
+        });
+    }
+    #requireMac() { if (this.#platform !== 'darwin')
+        throw new UsageError('shard menubar requires macOS 14 or later.'); }
+    async #version(app) {
+        const file = join(app, 'Contents', 'Info.plist');
+        const id = (await this.#run('/usr/bin/plutil', ['-extract', 'CFBundleIdentifier', 'raw', '-o', '-', file])).trim();
+        if (id !== BUNDLE_ID || lstatSync(app).isSymbolicLink())
+            throw new UsageError(`Refusing to replace an unrelated app at ${app}.`);
+        const version = (await this.#run('/usr/bin/plutil', ['-extract', 'CFBundleVersion', 'raw', '-o', '-', file])).trim();
+        compareBundleVersions(version, version);
+        return version;
+    }
+    async #control(action, ...args) {
+        return parseNativeStatus(await this.#run(join(this.app, 'Contents', 'MacOS', 'ShardfluxMenuBar'), ['--control', action, ...args]));
+    }
+    async status() {
+        this.#requireMac();
+        if (!existsSync(this.app))
+            return { installed: false, version: null, running: false, pids: [], login: 'off' };
+        const version = await this.#version(this.app);
+        return { installed: true, version, ...await this.#control('status') };
+    }
+    async #stripQuarantine() {
+        const attributes = await this.#run('/usr/bin/xattr', ['-lr', this.app]);
+        if (attributes.includes('com.apple.quarantine'))
+            await this.#run('/usr/bin/xattr', ['-dr', 'com.apple.quarantine', this.app]);
+    }
+    async stop() {
+        const current = await this.status();
+        if (!current.installed || !current.running)
+            return current;
+        await this.#control('stop');
+        for (let i = 0; i < 20; i++) {
+            const status = await this.status();
+            if (!status.running)
+                return status;
+            await new Promise(resolve => setTimeout(resolve, 100));
+        }
+        throw new UsageError('Shardflux is still stopping. Run shard menubar status before retrying.');
+    }
+    async login(value) {
+        if (!(await this.status()).installed)
+            throw new UsageError('Run shard menubar start before changing launch at login.');
+        await this.#control('login', value);
+        return this.status();
+    }
+    async start(configDir, apiUrl) {
+        this.#requireMac();
+        const source = this.#packageApp(), sourceVersion = await this.#version(source);
+        const current = await this.status();
+        if (!current.installed || compareBundleVersions(current.version, sourceVersion) < 0) {
+            // Verify the source before stopping or replacing any existing app.
+            await this.#run('/usr/bin/codesign', ['--verify', '--deep', '--strict', source]);
+            mkdirSync(dirname(this.app), { recursive: true });
+            const stage = mkdtempSync(join(dirname(this.app), '.Shardflux-install-'));
+            const staged = join(stage, 'Shardflux.app'), backup = join(stage, 'previous.app');
+            let committed = false, restored = false;
+            try {
+                cpSync(source, staged, { recursive: true, dereference: false });
+                if (current.running)
+                    await this.stop();
+                if (current.installed)
+                    renameSync(this.app, backup);
+                try {
+                    renameSync(staged, this.app);
+                    committed = true;
+                }
+                catch (error) {
+                    if (existsSync(backup)) {
+                        try {
+                            renameSync(backup, this.app);
+                            restored = true;
+                        }
+                        catch {
+                            throw new UsageError(`Could not restore the previous app. It is preserved at ${backup}.`);
+                        }
+                    }
+                    throw error;
+                }
+            }
+            finally {
+                if (committed || restored || !existsSync(backup))
+                    rmSync(stage, { recursive: true, force: true });
+            }
+        }
+        await this.#stripQuarantine();
+        if (!(await this.status()).running) {
+            mkdirSync(configDir, { recursive: true, mode: 0o700 });
+            const log = join(configDir, 'menubar.log');
+            await this.#run('/usr/bin/open', ['-g', this.app, '--env', `SHARDFLUX_CONFIG_DIR=${configDir}`, '--env', `SHARDFLUX_API_URL=${apiUrl}`, '--stdout', log, '--stderr', log]);
+        }
+        for (let i = 0; i < 20; i++) {
+            const status = await this.status();
+            if (status.running)
+                return status;
+            await new Promise(resolve => setTimeout(resolve, 100));
+        }
+        throw new UsageError(`Shardflux did not start. Check ${join(configDir, 'menubar.log')}.`);
+    }
+}
+/** Only the command center consumes this hint. It reads status, never resolves or installs the optional package. */
+export async function menubarHint(dir, manager = new MenubarManager()) {
+    if (process.platform !== 'darwin')
+        return undefined;
+    const store = new AgentStateStore(dir);
+    if (store.read().menubar_hint_shown === true)
+        return undefined;
+    try {
+        if ((await manager.status()).running)
+            return undefined;
+    }
+    catch {
+        return undefined;
+    }
+    store.update(doc => { doc.menubar_hint_shown = true; });
+    return 'Menu bar: shard menubar start';
+}
+export const MENUBAR_HANDLERS = Object.fromEntries(['start', 'stop', 'status'].map(action => {
+    const handler = async (ctx, values) => {
+        if (values.login !== undefined && !['on', 'off'].includes(String(values.login)))
+            throw new UsageError('--login must be on or off.');
+        const manager = new MenubarManager({ home: ctx.io.env.HOME || homedir(), signal: ctx.signal });
+        let status = action === 'start' ? await manager.start(ctx.store.dir, ctx.apiUrl) : action === 'stop' ? await manager.stop() : await manager.status();
+        if (values.login === 'on' || values.login === 'off')
+            status = await manager.login(values.login);
+        ctx.io.stdout.write(ctx.json ? json(status) : `Menu bar: ${status.running ? 'running' : 'stopped'}${status.installed ? ` · app ${status.version}` : ' · not installed'} · login ${status.login}\n`);
+        return 0;
+    };
+    return [`menubar ${action}`, handler];
+}));

package/dist/project-identity.d.ts

@@ -0,0 +1,14 @@
+/** Transport and credentials are not project identity. Keep repository path case on case-sensitive hosts. */
+export declare function normalizeRemote(remote: string, folder?: string): string;
+export declare function projectSlug(remote: string | null, folder: string): string;
+export declare function projectIdentity(path: string): {
+    folder: string;
+    slug: string;
+    remote: string | null;
+};
+export declare function projectLabels(project: ReturnType<typeof projectIdentity>, agent: string, app: 'claude' | 'codex'): {
+    shard_project: string;
+    repo_remote: string;
+    agent: string;
+    app: "claude" | "codex";
+};

package/dist/project-identity.js

@@ -0,0 +1,61 @@
+import { execFileSync } from 'node:child_process';
+import { statSync, realpathSync } from 'node:fs';
+import { basename, resolve } from 'node:path';
+import { UsageError } from "./errors.js";
+/** Transport and credentials are not project identity. Keep repository path case on case-sensitive hosts. */
+export function normalizeRemote(remote, folder = process.cwd()) {
+    const raw = remote.trim();
+    const scp = /^(?:[^/@:]+@)?([^/:]+):(.+)$/.exec(raw);
+    let url;
+    try {
+        url = new URL(scp && !raw.includes('://') ? `ssh://${scp[1]}/${scp[2]}` : raw);
+    }
+    catch {
+        if (raw.includes('://'))
+            throw new UsageError('git remote URL is invalid');
+        return `file://${resolve(folder, raw).replace(/\/+$/, '').replace(/\.git$/, '')}`;
+    }
+    if (!['https:', 'http:', 'ssh:', 'git:', 'file:'].includes(url.protocol))
+        throw new UsageError('unsupported git remote transport');
+    if (url.protocol === 'file:')
+        return `file://${url.pathname.replace(/\/+$/, '').replace(/\.git$/, '')}`;
+    const host = url.hostname.toLowerCase();
+    const port = url.port && !((url.protocol === 'ssh:' && url.port === '22') || (url.protocol === 'git:' && url.port === '9418')) ? `:${url.port}` : '';
+    let path = url.pathname.replace(/\/+$/, '').replace(/\.git$/, '').replace(/^\/+/, '');
+    if (host === 'github.com' || host === 'bitbucket.org')
+        path = path.toLowerCase();
+    return `https://${host}${port}/${path}`;
+}
+export function projectSlug(remote, folder) {
+    const name = remote ? remote.split('/').at(-1) : basename(folder);
+    const slug = name.normalize('NFKD').replace(/[\u0300-\u036f]/g, '').toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^[^a-z0-9]+|[^a-z0-9]+$/g, '').slice(0, 96);
+    if (!slug)
+        throw new UsageError('project name has no letters or digits; use a named project folder');
+    return slug;
+}
+export function projectIdentity(path) {
+    let folder;
+    try {
+        folder = realpathSync(resolve(path));
+        if (!statSync(folder).isDirectory())
+            throw new Error('not a directory');
+    }
+    catch {
+        throw new UsageError('project path must name an accessible directory');
+    }
+    let raw = null;
+    try {
+        raw = execFileSync('git', ['-C', folder, 'remote', 'get-url', 'origin'], { encoding: 'utf8', timeout: 5_000, stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    }
+    catch {
+        // A folder without an origin is a project too.
+    }
+    const remote = raw ? normalizeRemote(raw, folder) : null;
+    const slug = projectSlug(remote, folder);
+    return { folder, slug, remote };
+}
+export function projectLabels(project, agent, app) {
+    if (project.remote && project.remote.length > 256)
+        throw new UsageError('normalized repository remote exceeds the 256-character workspace label limit');
+    return { shard_project: project.slug, repo_remote: project.remote ?? '', agent, app };
+}

package/dist/project-sync-manifest.d.ts

@@ -0,0 +1,27 @@
+import type { FileManifest, FileManifestEntry } from '@shardflux/sdk';
+export declare const MAX_SYNC_FILE_BYTES: number;
+export declare const MAX_SYNC_ENTRIES = 20000;
+export type Manifest = Record<string, FileManifestEntry>;
+export type Common = Record<string, string>;
+export interface SyncChange {
+    path: string;
+    winner: 'local' | 'remote';
+    conflict: boolean;
+}
+export declare function validSyncPath(path: string): boolean;
+export declare function excludedSyncPath(path: string): boolean;
+export declare function contentIdentity(entry?: FileManifestEntry): string;
+/** Deletions have an observation timestamp: a detached filesystem has no deletion clock. Ties favor the laptop. */
+export declare function diffManifests(local: Manifest, remote: Manifest, common: Common, observedAt?: number, blocked?: Set<string>): SyncChange[];
+export declare function parseManifest(manifest: FileManifest): Manifest;
+export declare function projectGit(folder: string, args: string[], signal?: AbortSignal, input?: string): Promise<string>;
+/** Uses the actual Git implementation rather than an approximation of gitignore. */
+export declare function selectedProjectPaths(folder: string, signal?: AbortSignal): Promise<string[]>;
+export declare function ignoredProjectPaths(folder: string, paths: string[], signal?: AbortSignal): Promise<string[]>;
+/** Refuse parent symlinks, including a tracked file beneath a submodule/link. */
+export declare function projectFilePath(folder: string, path: string): Promise<string>;
+export type LocalHashCache = Map<string, {
+    metadata: string;
+    entry: FileManifestEntry;
+}>;
+export declare function localManifest(folder: string, signal?: AbortSignal, cache?: LocalHashCache, known?: string[]): Promise<FileManifest>;