@yijiancaotang/cli 1.1.0 → 1.2.1

package/dist/project-binding.js

@@ -0,0 +1,370 @@
+import { createHash, randomBytes } from "node:crypto";
+import { lstat, realpath } from "node:fs/promises";
+import { isAbsolute, join, parse, relative, resolve, sep } from "node:path";
+import { asRecord, CliError } from "./errors.js";
+import { OwnedTree } from "./installation.js";
+import { acquireLocalLock } from "./local-lock.js";
+const serviceBase = "/api/v1/agent";
+const maxMapBytes = 256 * 1024;
+const maxEntries = 256;
+const hash = (bytes) => createHash("sha256").update(bytes).digest("hex");
+const uuid = (value) => typeof value === "string" && /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/i.test(value);
+const ownerID = (value) => typeof value === "string" && /^[A-Za-z0-9_-]{1,128}$/.test(value);
+const hex = (value) => typeof value === "string" && /^[a-f0-9]{64}$/.test(value);
+const keys = (value, expected) => Object.keys(value).sort().join(",") === [...expected].sort().join(",");
+const safePath = (value) => typeof value === "string" && value.length > 0 && value.length <= 4096 && isAbsolute(value) && resolve(value) === value && !/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/u.test(value);
+const within = (parent, child) => { const part = relative(parent, child); return part !== ".." && !part.startsWith(`..${sep}`) && !isAbsolute(part); };
+const sameIdentity = (a, b) => a.dev === b.dev && a.ino === b.ino && a.uid === b.uid;
+const sameFacts = (a, b) => a.canonical_path === b.canonical_path && sameIdentity(a, b) && a.mode === b.mode;
+class StateError extends Error {
+    reason;
+    constructor(reason) {
+        super("Local project binding metadata is unavailable or unsafe");
+        this.reason = reason;
+    }
+}
+function result(operation, status, reason) { return { schema_version: 1, operation, status, ...(reason ? { reason } : {}) }; }
+function changedPreview() { throw new CliError("project_binding_preview_changed", "本机项目关联的确认范围已变化，未写入。", "重新查看当前目录、账号、服务和项目的预览；摘要不能替代本人明确同意。", 2); }
+function projectOptions(options) {
+    if (!options || !uuid(options.projectId) || options.includeSubdirs !== undefined && typeof options.includeSubdirs !== "boolean")
+        throw new CliError("invalid_arguments", "项目关联参数无效。", "指定真实项目ID；子目录范围须单独预览确认，不扫描目录或猜测同名项目。", 2);
+    return { projectId: options.projectId.toLowerCase(), includeSubdirs: options.includeSubdirs === true };
+}
+function identity(ctx) {
+    if (!ownerID(ctx.verifiedOwnerId) || ctx.serviceBase !== serviceBase || typeof ctx.apiBaseUrl !== "string" || ctx.apiBaseUrl.trim() !== ctx.apiBaseUrl)
+        return;
+    try {
+        const url = new URL(ctx.apiBaseUrl);
+        if (url.username || url.password || url.search || url.hash || url.pathname !== "/" || (url.protocol !== "https:" && !(url.protocol === "http:" && ["127.0.0.1", "localhost", "[::1]"].includes(url.hostname))))
+            return;
+        return { origin: url.origin, owner: ctx.verifiedOwnerId };
+    }
+    catch {
+        return;
+    }
+}
+async function directoryFacts(path) {
+    if (!safePath(path) || typeof process.getuid !== "function")
+        throw new StateError("directory_unsafe");
+    const uid = process.getuid(), root = parse(path).root, ancestors = [];
+    let current = root;
+    for (const part of [null, ...relative(root, path).split(sep).filter(Boolean)]) {
+        if (part !== null)
+            current = join(current, part);
+        const info = await lstat(current, { bigint: true }), mode = Number(info.mode & 4095n), owner = Number(info.uid), final = current === path;
+        const stickySystemAncestor = !final && owner === 0 && (mode & 0o1000) !== 0;
+        if (!info.isDirectory() || (final ? owner !== uid : owner !== uid && owner !== 0) || (mode & 0o022) !== 0 && !stickySystemAncestor)
+            throw new StateError("directory_unsafe");
+        ancestors.push({ canonical_path: current, dev: info.dev.toString(), ino: info.ino.toString(), uid: owner, mode });
+    }
+    if (await realpath(path) !== path)
+        throw new StateError("directory_unsafe");
+    return { facts: ancestors.at(-1), ancestors };
+}
+async function base(ctx, operation, requireLocal) {
+    if (requireLocal && ctx.localScopeConfirmed !== true)
+        return result(operation, "local_scope_required", "independent_local_workspace_not_confirmed");
+    const who = identity(ctx);
+    if (!who || typeof ctx.readProject !== "function")
+        return result(operation, "unknown", "identity_or_service_unverified");
+    try {
+        const home = await directoryFacts(ctx.homeDir), directory = await directoryFacts(ctx.cwd), tree = new OwnedTree(ctx.homeDir);
+        await tree.directory(ctx.homeDir, false, async () => true);
+        return { tree, home: home.facts, directory: directory.facts, ancestors: directory.ancestors, uid: process.getuid(), ...who, root: join(ctx.homeDir, ".caotang", "project-bindings") };
+    }
+    catch {
+        return result(operation, "invalid", "directory_unsafe_or_changed");
+    }
+}
+function isBase(value) { return "tree" in value; }
+function metadata(b) { return { service: { origin: b.origin, service_base: serviceBase }, owner_id: b.owner }; }
+async function verifyBase(ctx, b) {
+    const who = identity(ctx);
+    if (ctx.localScopeConfirmed !== true || !who || who.origin !== b.origin || who.owner !== b.owner
+        || !sameFacts((await directoryFacts(ctx.homeDir)).facts, b.home) || !sameFacts((await directoryFacts(ctx.cwd)).facts, b.directory))
+        throw new StateError("scope_changed");
+}
+async function checkedProject(ctx, id, operation) {
+    let value;
+    try {
+        value = await ctx.readProject(id);
+    }
+    catch {
+        return result(operation, "unknown", "project_validation_unavailable");
+    }
+    if (!value)
+        return result(operation, "invalid", "project_not_accessible");
+    if (["hidden", "archived", "deleted"].includes(value.status))
+        return result(operation, "invalid", "project_not_eligible");
+    if (!uuid(value.id) || value.id.toLowerCase() !== id || !["active", "paused", "draft"].includes(value.status)
+        || typeof value.title !== "string" || !value.title.trim() || [...value.title].length > 80 || /[\p{Cc}\uD800-\uDFFF]/u.test(value.title))
+        return result(operation, "unknown", "project_metadata_unverified");
+    return { id, title: value.title, status: value.status };
+}
+function isProject(value) { return "id" in value; }
+function bindDigest(b, project, includeSubdirs) {
+    return hash(JSON.stringify({ schema_version: 1, operation: "bind", home: b.home, directory: b.directory, uid: b.uid, origin: b.origin, service_base: serviceBase, owner_id: b.owner, project, include_subdirs: includeSubdirs, scope: "independent_local_only" }));
+}
+async function bindingPreview(ctx, options) {
+    const wanted = projectOptions(options), operation = "project_bind_preview", b = await base(ctx, operation, false);
+    if (!isBase(b))
+        return b;
+    const project = await checkedProject(ctx, wanted.projectId, operation);
+    if (!isProject(project))
+        return project;
+    try {
+        if (!sameFacts((await directoryFacts(ctx.cwd)).facts, b.directory) || !sameFacts((await directoryFacts(ctx.homeDir)).facts, b.home))
+            return result(operation, "invalid", "directory_changed_during_preview");
+    }
+    catch {
+        return result(operation, "invalid", "directory_changed_during_preview");
+    }
+    return { b, project, includeSubdirs: wanted.includeSubdirs, preview: {
+            ...result(operation, "confirmation_required"), ...metadata(b), directory: { canonical_path: b.directory.canonical_path, include_subdirs: wanted.includeSubdirs }, project,
+            preview_digest: bindDigest(b, project, wanted.includeSubdirs), requires_local_scope_confirmation: true, local_write_only: true,
+        } };
+}
+export async function previewProjectBinding(ctx, options) {
+    const outcome = await bindingPreview(ctx, options);
+    return "preview" in outcome ? outcome.preview : outcome;
+}
+function storedFacts(value) {
+    const v = asRecord(value);
+    if (!v || !keys(v, ["canonical_path", "dev", "ino", "uid", "mode"]) || !safePath(v.canonical_path)
+        || typeof v.dev !== "string" || !/^\d{1,40}$/.test(v.dev) || typeof v.ino !== "string" || !/^\d{1,40}$/.test(v.ino)
+        || typeof v.uid !== "number" || !Number.isSafeInteger(v.uid) || v.uid < 0 || typeof v.mode !== "number" || !Number.isInteger(v.mode) || v.mode < 0 || v.mode > 0o7777)
+        throw new StateError("local_metadata_malformed");
+    return { canonical_path: v.canonical_path, dev: v.dev, ino: v.ino, uid: v.uid, mode: v.mode };
+}
+function json(bytes) {
+    try {
+        const raw = bytes.toString("utf8");
+        if (!Buffer.from(raw, "utf8").equals(bytes))
+            throw Error();
+        const value = asRecord(JSON.parse(raw));
+        if (!value)
+            throw Error();
+        return value;
+    }
+    catch {
+        throw new StateError("local_metadata_malformed");
+    }
+}
+async function localState(b, create) {
+    const path = join(b.root, "local-state.json");
+    let bytes = await b.tree.read(path, 16384, 0o600);
+    if (!bytes && create) {
+        const fresh = { schema_version: 1, scope: "user_confirmed_independent_local", local_state_id: randomBytes(32).toString("hex"), home: b.home };
+        try {
+            await b.tree.writeNew(path, Buffer.from(JSON.stringify(fresh)), 0o600);
+        }
+        catch (error) {
+            if (!(error instanceof CliError) || error.code !== "installation_conflict")
+                throw error;
+        }
+        bytes = await b.tree.read(path, 16384, 0o600);
+        if (!bytes)
+            throw new StateError("local_state_unconfirmed");
+    }
+    if (!bytes)
+        return null;
+    const value = json(bytes);
+    if (!keys(value, ["schema_version", "scope", "local_state_id", "home"]) || value.schema_version !== 1 || value.scope !== "user_confirmed_independent_local" || !hex(value.local_state_id))
+        throw new StateError("local_metadata_malformed");
+    const home = storedFacts(value.home);
+    if (!sameFacts(home, b.home))
+        throw new StateError("local_home_identity_changed");
+    return { schema_version: 1, scope: "user_confirmed_independent_local", local_state_id: value.local_state_id, home };
+}
+function namespace(b, state) {
+    return hash(JSON.stringify({ schema_version: 1, local_state_id: state.local_state_id, home: state.home, uid: b.uid, origin: b.origin, service_base: serviceBase, owner_id: b.owner }));
+}
+async function storedMap(b, state) {
+    const ns = namespace(b, state), directory = join(b.root, "namespaces", ns), path = join(directory, "bindings.json"), bytes = await b.tree.read(path, maxMapBytes, 0o600);
+    if (!bytes)
+        return { namespace: ns, path, directory, bytes: null, value: { schema_version: 1, namespace: ns, entries: [] } };
+    const value = json(bytes);
+    if (!keys(value, ["schema_version", "namespace", "entries"]) || value.schema_version !== 1 || value.namespace !== ns || !Array.isArray(value.entries) || value.entries.length > maxEntries)
+        throw new StateError("local_metadata_malformed");
+    const entries = value.entries.map((raw) => {
+        const item = asRecord(raw);
+        if (!item || !keys(item, ["directory", "project_id", "include_subdirs"]) || !uuid(item.project_id) || typeof item.include_subdirs !== "boolean")
+            throw new StateError("local_metadata_malformed");
+        const directory = storedFacts(item.directory);
+        if (directory.uid !== b.uid)
+            throw new StateError("local_metadata_malformed");
+        return { directory, project_id: item.project_id.toLowerCase(), include_subdirs: item.include_subdirs };
+    });
+    if (new Set(entries.map(entry => entry.directory.canonical_path)).size !== entries.length)
+        throw new StateError("local_metadata_malformed");
+    return { namespace: ns, path, directory, bytes, value: { schema_version: 1, namespace: ns, entries } };
+}
+function selection(b, entries) {
+    const candidates = entries.filter(entry => entry.directory.canonical_path === b.directory.canonical_path || entry.include_subdirs && within(entry.directory.canonical_path, b.directory.canonical_path))
+        .sort((a, z) => z.directory.canonical_path.length - a.directory.canonical_path.length);
+    if (candidates.length)
+        return { entry: candidates[0], inherited: candidates[0].directory.canonical_path !== b.directory.canonical_path };
+    const moved = entries.some(entry => sameIdentity(entry.directory, b.directory) || entry.include_subdirs && b.ancestors.some(ancestor => sameIdentity(entry.directory, ancestor)));
+    return { moved };
+}
+function stateFailure(operation, error) {
+    if (error instanceof StateError)
+        return result(operation, "invalid", error.reason);
+    if (error instanceof CliError && ["project_binding_busy", "project_binding_update_unknown"].includes(error.code))
+        return result(operation, "unknown", error.code);
+    return result(operation, "invalid", "local_state_unsafe_or_unavailable");
+}
+async function changeMap(b, map, entries) {
+    if (entries.length > maxEntries)
+        throw new StateError("local_binding_capacity_exceeded");
+    const value = { schema_version: 1, namespace: map.namespace, entries: [...entries].sort((a, z) => a.directory.canonical_path.localeCompare(z.directory.canonical_path)) };
+    const after = Buffer.from(JSON.stringify(value));
+    if (after.length > maxMapBytes)
+        throw new StateError("local_binding_capacity_exceeded");
+    if (map.bytes?.equals(after))
+        return false;
+    let writeAttempted = false;
+    try {
+        if (!map.bytes) {
+            writeAttempted = true;
+            await b.tree.writeNew(map.path, after, 0o600);
+        }
+        else {
+            const journal = Buffer.from(JSON.stringify({ schema_version: 1, before_sha256: hash(map.bytes), after_sha256: hash(after), before_base64: map.bytes.toString("base64"), after_base64: after.toString("base64") }));
+            await b.tree.writeNew(join(map.directory, "history", `${hash(map.bytes)}.${hash(after)}.json`), journal, 0o600);
+            const entry = { path: map.path, before: map.bytes, after, mode: 0o600, label: "project_bindings" };
+            writeAttempted = true;
+            try {
+                await b.tree.replaceManaged(entry);
+            }
+            catch {
+                try {
+                    await b.tree.replaceManaged(entry, true);
+                }
+                catch { /* Keep recovery bytes; never reset an unverified inode. */ }
+                throw new StateError("local_update_unconfirmed");
+            }
+        }
+        if (!(await b.tree.read(map.path, maxMapBytes, 0o600))?.equals(after))
+            throw new StateError("local_update_unconfirmed");
+    }
+    catch (error) {
+        if (!writeAttempted)
+            throw error;
+        throw new CliError("project_binding_update_unknown", "本机关联更新未完成最终核对。", "保留现有元数据和恢复记录，由本人核对；不要自动重写或影响草堂项目。", 6);
+    }
+    return true;
+}
+async function locked(b, state, action) {
+    const ns = namespace(b, state), directory = join(b.root, "namespaces", ns), lockPath = join(directory, ".binding.lock");
+    const release = await b.tree.directory(directory, true, async (parents) => acquireLocalLock(lockPath, parents.at(-1), {
+        unsafe: () => new StateError("local_lock_unsafe"),
+        busy: () => new CliError("project_binding_busy", "另一项本机项目关联操作未完成。", "先等待本机操作结束；状态未知时不要删锁或强制覆盖。", 6),
+    }));
+    if (!release)
+        throw new StateError("local_lock_unavailable");
+    try {
+        return await action(await storedMap(b, state));
+    }
+    finally {
+        release();
+    }
+}
+export async function confirmProjectBinding(ctx, options) {
+    const operation = "project_bind";
+    if (ctx.localScopeConfirmed !== true || options.localScopeConfirmed !== true)
+        return result(operation, "local_scope_required", "independent_local_workspace_not_confirmed");
+    const outcome = await bindingPreview(ctx, options);
+    if (!("preview" in outcome))
+        return { ...outcome, operation };
+    if (!hex(options.previewDigest) || options.previewDigest !== outcome.preview.preview_digest)
+        changedPreview();
+    const { b, project, includeSubdirs } = outcome;
+    try {
+        await verifyBase(ctx, b);
+        const state = await localState(b, true);
+        if (!state)
+            throw new StateError("local_state_unconfirmed");
+        const changed = await locked(b, state, async (map) => {
+            await verifyBase(ctx, b);
+            const entries = map.value.entries.filter(entry => entry.directory.canonical_path !== b.directory.canonical_path);
+            entries.push({ directory: b.directory, project_id: project.id, include_subdirs: includeSubdirs });
+            return changeMap(b, map, entries);
+        });
+        return { ...result(operation, "bound"), ...metadata(b), directory: { canonical_path: b.directory.canonical_path, include_subdirs: includeSubdirs }, project, inherited: false, changed, local_write_only: true };
+    }
+    catch (error) {
+        return stateFailure(operation, error);
+    }
+}
+export async function readProjectBinding(ctx) {
+    const operation = "project_binding", b = await base(ctx, operation, true);
+    if (!isBase(b))
+        return b;
+    try {
+        const state = await localState(b, false);
+        if (!state)
+            return result(operation, "not_bound", "no_local_state_in_current_scope");
+        const map = await storedMap(b, state), chosen = selection(b, map.value.entries);
+        if (!chosen.entry)
+            return result(operation, chosen.moved ? "invalid" : "not_bound", chosen.moved ? "directory_moved" : "no_binding_in_current_scope");
+        const entry = chosen.entry;
+        if (!sameFacts((await directoryFacts(entry.directory.canonical_path)).facts, entry.directory))
+            return result(operation, "invalid", "directory_identity_changed");
+        const project = await checkedProject(ctx, entry.project_id, operation);
+        if (!isProject(project))
+            return project;
+        await verifyBase(ctx, b);
+        // A different local operation may have changed the map while the project
+        // validation was awaiting the server. Never label that old selection current.
+        const currentState = await localState(b, false);
+        if (!currentState || currentState.local_state_id !== state.local_state_id || !map.bytes
+            || !(await b.tree.read(map.path, maxMapBytes, 0o600))?.equals(map.bytes))
+            return result(operation, "unknown", "binding_changed_during_validation");
+        return { ...result(operation, "bound"), ...metadata(b), directory: { canonical_path: entry.directory.canonical_path, include_subdirs: entry.include_subdirs }, project, inherited: chosen.inherited === true };
+    }
+    catch (error) {
+        return stateFailure(operation, error);
+    }
+}
+function unbindDigest(b, map, entry) {
+    return hash(JSON.stringify({ schema_version: 1, operation: "unbind_exact", home: b.home, directory: b.directory, origin: b.origin, service_base: serviceBase, owner_id: b.owner, namespace: map.namespace, map_sha256: hash(map.bytes), entry }));
+}
+export async function unbindProjectBinding(ctx, options = {}) {
+    const operation = options.previewDigest === undefined ? "project_unbind_preview" : "project_unbind", b = await base(ctx, operation, true);
+    if (!isBase(b))
+        return b;
+    if (options.previewDigest !== undefined && options.localScopeConfirmed !== true)
+        return result(operation, "local_scope_required", "independent_local_workspace_not_confirmed");
+    try {
+        const state = await localState(b, false);
+        if (!state)
+            return result(operation, "not_bound", "no_local_state_in_current_scope");
+        const map = await storedMap(b, state), exact = map.value.entries.find(entry => entry.directory.canonical_path === b.directory.canonical_path);
+        if (!exact) {
+            const inherited = selection(b, map.value.entries).entry;
+            return result(operation, inherited ? "inherited_binding_requires_root" : "not_bound", inherited ? "confirm_at_exact_binding_directory" : "no_binding_in_current_scope");
+        }
+        if (!map.bytes)
+            throw new StateError("local_metadata_malformed");
+        const digest = unbindDigest(b, map, exact);
+        if (options.previewDigest === undefined)
+            return { ...result(operation, "confirmation_required"), ...metadata(b), directory: { canonical_path: b.directory.canonical_path, include_subdirs: exact.include_subdirs }, preview_digest: digest, requires_local_scope_confirmation: true, local_write_only: true };
+        if (!hex(options.previewDigest) || options.previewDigest !== digest)
+            changedPreview();
+        await verifyBase(ctx, b);
+        const changed = await locked(b, state, async (current) => {
+            const row = current.value.entries.find(entry => entry.directory.canonical_path === b.directory.canonical_path);
+            if (!row || !current.bytes || unbindDigest(b, current, row) !== options.previewDigest)
+                changedPreview();
+            await verifyBase(ctx, b);
+            return changeMap(b, current, current.value.entries.filter(entry => entry.directory.canonical_path !== b.directory.canonical_path));
+        });
+        return { ...result(operation, "unbound"), ...metadata(b), directory: { canonical_path: b.directory.canonical_path, include_subdirs: exact.include_subdirs }, changed, local_write_only: true };
+    }
+    catch (error) {
+        if (error instanceof CliError && error.code === "project_binding_preview_changed")
+            throw error;
+        return stateFailure(operation, error);
+    }
+}