spect8-vault 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,24 @@
-# Temporary Holding Version
+# Spect8 + Vault
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Publication candidate — not yet published to npm. Requires Node 22.12 or newer.
+
+After publication:
+
+```sh
+npm install -g spect8-vault
+spect8-vault setup
+```
+
+Setup runs Spect8's existing browser sign-in and IDE configuration, starts the bundled Vault engine, and asks for a device credential from https://www.spect8ai.tech/vault/workspace. Credentials stay in your local `.ctxlayer/spect8-vault.json` file. Do not share this file. Windows users should restrict access to their user profile; POSIX file permissions alone do not set Windows ACLs.
+
+Start a supported coding agent through the engine:
+
+```sh
+spect8-vault run claude
+```
+
+In a second terminal, run `spect8-vault sync`, pick a session, and confirm uploading. Stop with Ctrl+C. Sync is opt-in and runs in the foreground. Revoke the device in the workspace to remove its cloud access. The coding agent and its provider credentials must already be installed/configured. Use `spect8-vault doctor` for diagnostics and `spect8-vault engine --help` for advanced engine commands.
+
+## Maintainers
+
+Run `pnpm build`, then `node scripts/release/spect8.mjs` from the repository root. Run `npm pack` in `release/out/npm` to produce an installable archive. Validate the archive on supported operating systems before publishing. Confirm npm ownership of `spect8-vault` and availability of dependency `spect8-mcp@0.7.1`, then publish the reviewed archive. This package does not enable automatic background uploading or the librarian.

package/bin/bridge.mjs

@@ -0,0 +1,76 @@
+import { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+const cloud = new URL(process.env.VAULT_CLOUD_URL || '');
+if (cloud.protocol !== 'https:' && !['127.0.0.1', 'localhost'].includes(cloud.hostname))
+  throw new Error('Cloud URL must use HTTPS');
+const key = process.env.VAULT_DEVICE_KEY;
+const thread = process.env.VAULT_THREAD_ID;
+if (!key || !thread)
+  throw new Error(
+    'VAULT_DEVICE_KEY and VAULT_THREAD_ID required. Only this explicitly selected thread is uploaded.',
+  );
+if (process.env.VAULT_UPLOAD_CONTEXT !== '1')
+  throw new Error('Set VAULT_UPLOAD_CONTEXT=1 to consent to uploading this thread context to Spect8.');
+async function request(base, path, token, method = 'GET', body) {
+  const destination = new URL(path, base);
+  if (path.startsWith('/v1/') && new URL(base).pathname !== '/')
+    destination.pathname =
+      new URL(base).pathname.replace(/\/$/, '') + destination.pathname.replace(/^\/v1/, '');
+  const r = await fetch(destination, {
+    method,
+    redirect: 'error',
+    headers: { Authorization: `Bearer ${token}`, ...(body ? { 'Content-Type': 'application/json' } : {}) },
+    ...(body ? { body: JSON.stringify(body) } : {}),
+    signal: AbortSignal.timeout(20000),
+  });
+  if (!r.ok) throw new Error(`Request failed (${r.status})`);
+  return r.status === 204 ? {} : r.json();
+}
+console.log('Spect8 bridge active for selected thread. Stop with Ctrl+C.');
+let stop = false;
+process.on('SIGINT', () => {
+  stop = true;
+});
+process.on('SIGTERM', () => {
+  stop = true;
+});
+while (!stop) {
+  try {
+    const daemon = JSON.parse(
+      await readFile(join(process.env.CTX_HOME || join(homedir(), '.ctxlayer'), 'daemon.json'), 'utf8'),
+    );
+    const base = `http://127.0.0.1:${daemon.port}`;
+    const prefix = `/api/threads/${encodeURIComponent(thread)}`;
+    const [window, conversation, pending, projected] = await Promise.all(
+      ['window', 'conversation', 'pending', 'window?view=projected'].map((p) =>
+        request(base, `${prefix}/${p}`, daemon.token),
+      ),
+    );
+    await request(cloud, '/v1/bridge/snapshot', key, 'PUT', {
+      local_id: thread,
+      title: thread,
+      snapshot: { window, conversation, pending, projected },
+    });
+    const command = await request(cloud, '/v1/bridge/claim', key, 'POST', { local_id: thread });
+    if (command) {
+      let status = 'failed',
+        result = { message: 'Command belongs to another selected thread' };
+      if (command.local_id === thread && ['note', 'apply', 'undo', 'pending'].includes(command.action)) {
+        try {
+          result = await request(base, `${prefix}/${command.action}`, daemon.token, 'POST', command.payload);
+          status = 'done';
+        } catch (e) {
+          result = { message: e.message };
+        }
+      }
+      await request(cloud, `/v1/bridge/commands/${command.id}/result`, key, 'POST', {
+        status,
+        result: result || {},
+      });
+    }
+  } catch (e) {
+    console.error(e.message);
+  }
+  if (!stop) await new Promise((r) => setTimeout(r, 3000));
+}