amalgm 0.1.245 → 0.1.246

package/README.md

@@ -14,6 +14,18 @@ To move an existing install to the newest stable published build immediately, ru
 
 `amalgm login` opens a browser approval page, then registers the machine and stores its local tunnel/computer record in `~/.amalgm/computer.json`.
 
+After login, register local ground with the cloud-backed entity rail:
+
+```sh
+amalgm register path/to/file path/to/folder
+```
+
+`amalgm register` watches the selected local ground and saves its entity
+records and file contents to the signed-in user's private Amalgm cloud
+resource. `amalgm add` is reserved for the inverse operation—bringing an
+existing cloud entity onto a machine—and is not available until
+materialization ships.
+
 If you start from the Amalgm web app or are setting up a remote/headless machine, create a setup code from the web app and run:
 
 ```sh

package/lib/cli.js

@@ -114,10 +114,12 @@ function usage() {
     'amalgm - local computer runtime',
     '',
     'Usage:',
-    '  amalgm login [--app-url https://amalgm.ai] [--name "My Mac"] [--setup-code ABCD-EFGH-JKLM-NPQR] [--no-open] [--no-poll]',
+    '  amalgm login [--app-url https://amalgm.ai] [--name "My Mac"] [--setup-code ABCD-EFGH-JKLM-NPQR] [--no-open] [--no-poll] [--no-start]',
     '  amalgm start [--foreground] [--local-only] [--no-auto-update] [--branch main|preview] [--user <user-id>]',
     '  amalgm run [--local-only]',
     '  amalgm stop',
+    '  amalgm register [path ...] Register local ground (default: current directory)',
+    '  amalgm add <entity-uuid> [path] Add a cloud-backed entity to this machine (coming with materialization)',
     '  amalgm status',
     '  amalgm doctor',
     '  amalgm service [install|start|stop|status|uninstall] [--mode auto|systemd|launchd|windows|portable]',
@@ -466,7 +468,7 @@ function openBrowser(url) {
   }
 }
 
-async function registerComputer(appUrl, registrationToken, device, name) {
+async function registerComputer(appUrl, registrationToken, device, name, options = {}) {
   const registered = await requestJson(`${appUrl}/api/computers/register`, {
     method: 'POST',
     headers: {
@@ -498,7 +500,12 @@ async function registerComputer(appUrl, registrationToken, device, name) {
   if (!proxyTokenFromRecord(saved)) {
     console.log('HMAC proxy: not minted yet; Amalgm-managed egress will refresh after registration is complete.');
   }
-  console.log('Run `amalgm start` to connect this machine.');
+  if (options['no-start']) {
+    console.log('Runtime start skipped by --no-start. Run `amalgm start` to connect this machine.');
+    return saved;
+  }
+  console.log('Starting the canonical user runtime to complete local and cloud setup...');
+  await start({ user: saved.user_id });
   return saved;
 }
 
@@ -531,7 +538,7 @@ async function refreshStoredProxyToken(record) {
   return saved;
 }
 
-async function loginWithSetupCode(appUrl, setupCode, device, name) {
+async function loginWithSetupCode(appUrl, setupCode, device, name, options = {}) {
   const normalizedCode = normalizeSetupCode(setupCode);
   if (normalizedCode.length !== SETUP_CODE_LENGTH) {
     throw new Error('Invalid setup code. It should look like ABCD-EFGH-JKLM-NPQR.');
@@ -555,7 +562,7 @@ async function loginWithSetupCode(appUrl, setupCode, device, name) {
     throw new Error('Setup code was accepted, but no registration token was returned.');
   }
 
-  return registerComputer(appUrl, redeemed.computer_registration_token, device, name);
+  return registerComputer(appUrl, redeemed.computer_registration_token, device, name, options);
 }
 
 function appUrlFlag(appUrl) {
@@ -665,7 +672,7 @@ async function startCliLogin(appUrl, device, name, options) {
         console.log(`Approved by: ${polled.approved_by.label}`);
       }
       console.log('Browser approved. Registering this computer...');
-      return registerComputer(appUrl, polled.computer_registration_token, device, name);
+      return registerComputer(appUrl, polled.computer_registration_token, device, name, options);
     }
 
     if (polled.status === 'registered') {
@@ -692,7 +699,7 @@ async function login(options) {
   const setupCode = options['setup-code'] || options.code;
 
   if (setupCode) {
-    return loginWithSetupCode(appUrl, setupCode, device, name);
+    return loginWithSetupCode(appUrl, setupCode, device, name, options);
   }
 
   return startCliLogin(appUrl, device, name, options);
@@ -835,6 +842,45 @@ function relaunchCurrentCommandAfterLayoutChange() {
   return Number.isInteger(result.status) ? result.status : 0;
 }
 
+/** A login process begins before it knows the account scope. The registered
+ * runtime must not inherit that provisional `local` address or a caller's
+ * explicit AMALGM_DIR; launch the canonical process with the stable user id
+ * and let paths.js derive its user folder afresh. */
+function canonicalStartLaunch(userId, options = {}, inheritedEnv = process.env) {
+  const userScope = sanitizeScopeSegment(userId, '');
+  if (!userScope) throw new Error('cannot start the canonical runtime without a user id');
+  const env = {
+    ...inheritedEnv,
+    AMALGM_RUNTIME_USER_ID: userScope,
+    AMALGM_USER_SCOPE: userScope,
+    AMALGM_LAYOUT_RELAUNCHED: '1',
+  };
+  delete env.AMALGM_DIR;
+  delete env.AMALGM_RUNTIME_STATE_DIR;
+  delete env.AMALGM_RUNTIME_INSTANCE_ID;
+  const args = [path.join(__dirname, '..', 'bin', 'amalgm.js'), 'start', '--user', userScope];
+  if (options.foreground) args.push('--foreground');
+  if (options['local-only']) args.push('--local-only');
+  if (options['no-auto-update']) args.push('--no-auto-update');
+  if (options['no-service']) args.push('--no-service');
+  if (options.mode) args.push('--mode', String(options.mode));
+  return { args, env };
+}
+
+function relaunchStartForUser(userId, options = {}) {
+  const launch = canonicalStartLaunch(userId, options);
+  const result = spawnSync(process.execPath, launch.args, {
+    stdio: 'inherit',
+    env: launch.env,
+  });
+  if (result.error) throw result.error;
+  if (result.signal) {
+    process.kill(process.pid, result.signal);
+    return 1;
+  }
+  return Number.isInteger(result.status) ? result.status : 0;
+}
+
 function shouldRelaunchForAdoptedDir(adoption) {
   return Boolean(
     adoption?.dir
@@ -845,6 +891,13 @@ function shouldRelaunchForAdoptedDir(adoption) {
 }
 
 async function start(options) {
+  const requestedUser = typeof options.user === 'string'
+    ? sanitizeScopeSegment(options.user, '')
+    : '';
+  if (requestedUser && requestedUser !== AMALGM_RUNTIME_USER_SCOPE) {
+    process.exitCode = relaunchStartForUser(requestedUser, options);
+    return;
+  }
   ensureBaseDirs();
 
   if (await updateBeforeStartIfRequested(options)) {
@@ -1391,6 +1444,87 @@ async function logout() {
   console.log('Logged out locally. The device id remains so re-login updates the same computer.');
 }
 
+/**
+ * `amalgm register [path ...]` — register selected local ground with the running runtime.
+ *
+ * The CLI is a human interface over the runtime's operation, never a
+ * second implementation (docs/realtime-rails.md §3): it resolves the
+ * path, authenticates, and prints what came back. Every rule about what
+ * may be registered lives behind the endpoint.
+ */
+async function register(positionals) {
+  const targets = (positionals.length > 0 ? positionals : [process.cwd()])
+    .map((target) => path.resolve(target));
+
+  // A resolved port is not a running runtime — the manifest supplies a
+  // default whether or not anything listens — so both "no port for this
+  // scope" and "nothing answered" mean the same thing to the user.
+  const port = servicePorts().find(([name]) => name === 'amalgm-mcp')?.[1];
+  let answer = null;
+  if (port) {
+    try {
+      answer = await runtimePost(port, '/entities/register', { paths: targets });
+    } catch (error) {
+      if (error.code !== 'ECONNREFUSED') throw error;
+    }
+  }
+  if (!answer) {
+    console.error('Amalgm runtime is not running. Start it with `amalgm start`.');
+    process.exitCode = 1;
+    return;
+  }
+
+  if (answer.status !== 200) {
+    console.error(`Error: ${answer.payload?.error || `runtime responded ${answer.status}`}`);
+    process.exitCode = 1;
+    return;
+  }
+  const results = Array.isArray(answer.payload?.results)
+    ? answer.payload.results
+    : [{ rootPath: answer.payload?.rootPath, record: answer.payload?.record }];
+  for (let index = 0; index < results.length; index += 1) {
+    const { rootPath, record } = results[index];
+    const target = targets[index];
+    console.log(`Registered ${rootPath}`);
+    console.log(`  ${record.type}  ${record.uuid}`);
+    if (rootPath !== target) console.log(`  (${target} is already covered by this tree)`);
+  }
+}
+
+/** POST JSON to a local runtime service, carrying the runtime token. */
+function runtimePost(port, requestPath, body) {
+  const payload = JSON.stringify(body);
+  const token = readJson(RUNTIME_TOKEN_FILE, null)?.token || '';
+  return new Promise((resolve, reject) => {
+    const req = http.request({
+      host: '127.0.0.1',
+      port,
+      path: requestPath,
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        'content-length': Buffer.byteLength(payload),
+        ...(token ? { 'x-amalgm-runtime-token': token } : {}),
+      },
+    }, (res) => {
+      let text = '';
+      res.setEncoding('utf8');
+      res.on('data', (chunk) => { text += chunk; });
+      res.on('end', () => {
+        let parsed = null;
+        try {
+          parsed = JSON.parse(text);
+        } catch {
+          parsed = null;
+        }
+        resolve({ status: res.statusCode, payload: parsed });
+      });
+    });
+    req.on('error', reject);
+    req.end(payload);
+  });
+}
+
 async function main(argv) {
   const { command, options, positionals } = parseArgs(argv);
 
@@ -1413,6 +1547,10 @@ async function main(argv) {
     });
   }
   if (command === 'stop') return stop();
+  if (command === 'register') return register(positionals);
+  if (command === 'add') {
+    throw new Error('`amalgm add` is reserved for cloud-to-local materialization, which is not available yet. Use `amalgm register <path>` for local ground.');
+  }
   if (command === 'status') return status();
   if (command === 'doctor') return doctor();
   if (command === 'service') return serviceCommand(options, positionals);
@@ -1426,4 +1564,4 @@ async function main(argv) {
   process.exitCode = 1;
 }
 
-module.exports = { main };
+module.exports = { canonicalStartLaunch, main };

package/lib/layout.js

@@ -32,15 +32,40 @@ const path = require('path');
 const ROOT_MANIFEST_NAME = '.amalgm-root.json';
 const USER_MANIFEST_NAME = '.amalgm-user.json';
 const LAYOUT_VERSION = 1;
+const USER_HOME_MANIFEST_NAME = 'home.json';
+const USER_HOME_SCHEMA_VERSION = 1;
 
-// Per-user roots for platform primitives. Everything Amalgm owns for a user
-// lives under one of these; anything else on disk is the user's own project.
+// Stable per-user product namespaces. Their authority is NOT inferred from
+// their path: user content and exact platform-managed targets are declared
+// separately below (docs/user-cloud-bootstrap.md).
 const PRIMITIVE_DIRS = Object.freeze([
   'agents',
   'apps',
   'automations',
   'toolbox',
   'workspaces',
+  'system',
+]);
+
+const USER_HOME_ROOTS = Object.freeze([
+  { key: 'agents', relativePath: 'agents' },
+  { key: 'apps', relativePath: 'apps' },
+  { key: 'automations', relativePath: 'automations' },
+  { key: 'toolbox', relativePath: 'toolbox' },
+  { key: 'workspaces', relativePath: 'workspaces' },
+  { key: 'system', relativePath: 'system' },
+]);
+
+// Platform management is an exact-node fact. It deliberately does not
+// cascade from `system/`: human permissions may still inherit normally, while
+// only these particular entities are product-managed.
+const USER_HOME_EXACT_MANAGED = Object.freeze([
+  ...USER_HOME_ROOTS.map(({ key, relativePath }) => ({
+    key: `${key}-root`, relativePath, rootKey: key,
+  })),
+  { key: 'home-manifest', relativePath: 'system/home.json', rootKey: 'system' },
+  { key: 'defaults', relativePath: 'system/defaults', rootKey: 'system' },
+  { key: 'policy', relativePath: 'system/policy', rootKey: 'system' },
 ]);
 
 function readJson(file, fallback = null) {
@@ -56,6 +81,51 @@ function writeJson(file, data) {
   fs.writeFileSync(file, `${JSON.stringify(data, null, 2)}\n`, { mode: 0o600 });
 }
 
+function declaredUserHome(userDir) {
+  const root = path.resolve(userDir);
+  return {
+    schemaVersion: USER_HOME_SCHEMA_VERSION,
+    userDir: root,
+    roots: USER_HOME_ROOTS.map((entry) => ({
+      ...entry,
+      path: path.join(root, entry.relativePath),
+    })),
+    exactManaged: USER_HOME_EXACT_MANAGED.map((entry) => ({
+      ...entry,
+      path: path.join(root, entry.relativePath),
+      scope: 'exact',
+    })),
+  };
+}
+
+/**
+ * Materialize the fixed, safe bootstrap surface. This does not register or
+ * synchronize anything; runtime bootstrap calls the shared `amalgm register`
+ * boundary for that. Keeping those acts separate prevents login from growing
+ * a second identity registrar or silently enrolling machine-local state.
+ */
+function ensureUserHome(userDir) {
+  const declaration = declaredUserHome(userDir);
+  for (const root of declaration.roots) {
+    fs.mkdirSync(root.path, { recursive: true, mode: 0o700 });
+  }
+  for (const managed of declaration.exactManaged) {
+    if (path.extname(managed.path)) continue;
+    fs.mkdirSync(managed.path, { recursive: true, mode: 0o700 });
+  }
+
+  const manifest = declaration.exactManaged.find((entry) => entry.key === 'home-manifest');
+  if (manifest && !fs.existsSync(manifest.path)) {
+    writeJson(manifest.path, {
+      schemaVersion: USER_HOME_SCHEMA_VERSION,
+      kind: 'amalgm-user-home',
+      roots: declaration.roots.map(({ key, relativePath }) => ({ key, path: relativePath })),
+      exactManaged: declaration.exactManaged.map(({ key, relativePath, scope }) => ({ key, path: relativePath, scope })),
+    });
+  }
+  return declaration;
+}
+
 function lstatOrNull(target) {
   try {
     return fs.lstatSync(target);
@@ -249,17 +319,25 @@ function ensureUserDir(homeDir, { userId, email }) {
   const existing = findUserDirByUserId(homeDir, cleanId);
   if (existing) {
     if (cleanEmail && readUserManifest(existing)?.canonicalEmail !== cleanEmail) {
-      return adoptUserEmail(homeDir, { userId: cleanId, email: cleanEmail }).dir;
+      const adopted = adoptUserEmail(homeDir, { userId: cleanId, email: cleanEmail }).dir;
+      ensureUserHome(adopted);
+      return adopted;
     }
     indexUserFolder(homeDir, path.basename(existing), { userId: cleanId, email: cleanEmail });
+    ensureUserHome(existing);
     return existing;
   }
 
   const legacyDir = path.join(homeDir, 'users', sanitizeFolderSegment(cleanId));
   if (lstatOrNull(legacyDir)?.isDirectory()) {
     writeUserManifest(legacyDir, { userId: cleanId, email: cleanEmail });
-    if (cleanEmail) return adoptUserEmail(homeDir, { userId: cleanId, email: cleanEmail }).dir;
+    if (cleanEmail) {
+      const adopted = adoptUserEmail(homeDir, { userId: cleanId, email: cleanEmail }).dir;
+      ensureUserHome(adopted);
+      return adopted;
+    }
     indexUserFolder(homeDir, path.basename(legacyDir), { userId: cleanId, email: '' });
+    ensureUserHome(legacyDir);
     return legacyDir;
   }
 
@@ -268,6 +346,7 @@ function ensureUserDir(homeDir, { userId, email }) {
   fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
   writeUserManifest(dir, { userId: cleanId, email: cleanEmail });
   indexUserFolder(homeDir, folderName, { userId: cleanId, email: cleanEmail });
+  ensureUserHome(dir);
   return dir;
 }
 
@@ -323,8 +402,14 @@ module.exports = {
   PRIMITIVE_DIRS,
   ROOT_MANIFEST_NAME,
   USER_MANIFEST_NAME,
+  USER_HOME_EXACT_MANAGED,
+  USER_HOME_MANIFEST_NAME,
+  USER_HOME_ROOTS,
+  USER_HOME_SCHEMA_VERSION,
   adoptUserEmail,
+  declaredUserHome,
   emailFolderName,
+  ensureUserHome,
   ensureRootManifest,
   ensureUserDir,
   createCompatLink,