nylorun 0.4.0-beta → 0.5.0-beta

package/dist/stack/stacks.js

@@ -1,47 +1,52 @@
 import { existsSync } from "node:fs";
-import { readdir, readFile, rename, writeFile } from "node:fs/promises";
+import { mkdir, readdir, readFile, rename, rm, rmdir, writeFile } from "node:fs/promises";
 import { randomBytes } from "node:crypto";
 import { homedir } from "node:os";
-import { basename, join, resolve } from "node:path";
+import { basename, join, resolve, sep } from "node:path";
 import { CliError } from "../errors.js";
 /**
- * The machine's local stacks (tenancy.md §6): one installation per stack, each with its own
- * Host root `~/.nylorun/stacks/<name>/`, Compose project `nylorun-<name>`, ports and volumes.
- * `~/.nylorun` itself held the single stack of older releases (the legacy stack).
+ * The machine's local Tenants (tenancy.md §6): one installation per Tenant, each with its own
+ * Host root `~/.nylorun/tenants/<name>/`, Compose project `nylorun-<name>`, ports and volumes.
  */
-/** A stack name: also part of its Compose project, so Compose's rules apply. */
-export const STACK_NAME = /^[a-z0-9][a-z0-9_-]*$/;
-/** `~/.nylorun`: the stacks, and the legacy stack's files. Tests pass another directory. */
+/** The Tenant a command acts on outside a project when nothing names one. */
+export const DEFAULT_TENANT = "default";
+/** A Tenant name: also part of its Compose project, so Compose's rules apply. */
+export const TENANT_NAME = /^[a-z0-9][a-z0-9_-]*$/;
+/** `~/.nylorun`: the Tenants and the machine's settings. Tests pass another directory. */
 export function defaultNylorunRoot() {
     return resolve(join(homedir(), ".nylorun"));
 }
-export function stacksDir(base) {
-    return join(base, "stacks");
+export function tenantsDir(base) {
+    return join(base, "tenants");
 }
-export function stackRoot(base, name) {
-    return join(stacksDir(base), name);
+export function tenantRoot(base, name) {
+    return join(tenantsDir(base), name);
 }
-export function assertStackName(name, source) {
-    if (!STACK_NAME.test(name))
+export function assertTenantName(name, source) {
+    // A Tenant id, such as a NYLORUN_TENANT kept from an older release.
+    if (/^tn_/i.test(name))
+        throw new CliError(`${source} must be a Tenant's name, not a Tenant id: ${name}. "nylorun ls" lists the Tenants on this machine.`, 2);
+    if (!TENANT_NAME.test(name))
         throw new CliError(`${source} must be lowercase letters, digits, "-" or "_", starting with a letter or digit: ${name}`, 2);
     return name;
 }
-/** A directory name as a stack name: lowercased, other characters as `-`, trimmed. */
-export function sanitizeStackName(raw) {
+/** A directory name as a Tenant name: lowercased, other characters as `-`, trimmed. */
+export function sanitizeTenantName(raw) {
     const name = raw
         .toLowerCase()
         .replace(/[^a-z0-9_-]+/g, "-")
         .replace(/-{2,}/g, "-")
-        .replace(/^[-_]+|[-_]+$/g, "");
-    return name === "" ? "stack" : name;
+        .replace(/^[-_]+|[-_]+$/g, "")
+        .replace(/^tn_/, "tn-");
+    return name === "" ? "tenant" : name;
 }
-export function stackRecordPath(root) {
-    return join(root, "stack.json");
+export function tenantRecordPath(root) {
+    return join(root, "tenant.json");
 }
-export async function readStackRecord(root) {
+export async function readTenantRecord(root) {
     try {
-        const value = JSON.parse(await readFile(stackRecordPath(root), "utf8"));
-        if (typeof value?.name !== "string" || !STACK_NAME.test(value.name))
+        const value = JSON.parse(await readFile(tenantRecordPath(root), "utf8"));
+        if (typeof value?.name !== "string" || !TENANT_NAME.test(value.name))
             return undefined;
         return {
             format: 1,
@@ -53,64 +58,93 @@ export async function readStackRecord(root) {
         return undefined;
     }
 }
-export async function writeStackRecord(root, record) {
-    const path = stackRecordPath(root);
+export async function writeTenantRecord(root, record) {
+    const path = tenantRecordPath(root);
     const temporary = `${path}.${randomBytes(8).toString("hex")}.tmp`;
     const body = { format: 1, name: record.name, ...(record.project ? { project: record.project } : {}) };
     await writeFile(temporary, `${JSON.stringify(body, null, 2)}\n`, { mode: 0o600 });
     await rename(temporary, path);
 }
-/** The stacks under `<base>/stacks`, by name. */
-export async function listStacks(base) {
+/**
+ * The Tenants under `<base>/tenants`, by name: directories with a `tenant.json` (releases
+ * before 0.4 kept other directories there).
+ */
+export async function listTenants(base) {
     let entries;
     try {
-        entries = await readdir(stacksDir(base), { withFileTypes: true });
+        entries = await readdir(tenantsDir(base), { withFileTypes: true });
     }
     catch {
         return [];
     }
-    const stacks = [];
+    const tenants = [];
     for (const entry of entries) {
-        if (!entry.isDirectory() || !STACK_NAME.test(entry.name))
+        if (!entry.isDirectory() || !TENANT_NAME.test(entry.name))
             continue;
-        const root = stackRoot(base, entry.name);
-        const record = await readStackRecord(root);
-        stacks.push({ name: entry.name, root, ...(record ? { record } : {}) });
+        const root = tenantRoot(base, entry.name);
+        const record = await readTenantRecord(root);
+        if (record)
+            tenants.push({ name: entry.name, root, record });
     }
-    return stacks.sort((a, b) => a.name.localeCompare(b.name));
+    return tenants.sort((a, b) => a.name.localeCompare(b.name));
 }
 /**
- * The stack name for a project without a link: the directory's name, or the first `-2`,
- * `-3`, … suffix that no stack of another project directory holds. A stack this project
+ * The Tenant name for a project without a link: the directory's name, or the first `-2`,
+ * `-3`, … suffix that no Tenant of another project directory holds. A Tenant this project
  * directory created keeps its name.
  */
-export async function chooseStackName(base, projectDir) {
-    const name = sanitizeStackName(basename(projectDir));
-    const stacks = await listStacks(base);
+export async function chooseTenantName(base, projectDir) {
+    const name = sanitizeTenantName(basename(projectDir));
+    const tenants = await listTenants(base);
     const candidate = new RegExp(`^${name}(?:-[0-9]+)?$`);
-    const own = stacks.find((stack) => candidate.test(stack.name) && stack.record?.project === projectDir);
+    const own = tenants.find((tenant) => candidate.test(tenant.name) && tenant.record.project === projectDir);
     if (own)
         return own.name;
     for (let suffix = 1;; suffix += 1) {
         const next = suffix === 1 ? name : `${name}-${suffix}`;
-        if (!existsSync(stackRoot(base, next)))
+        if (!existsSync(tenantRoot(base, next)))
             return next;
     }
 }
-export function legacyStack(base) {
-    const compose = join(base, "stack", "compose.yaml");
-    if (!existsSync(compose))
-        return undefined;
-    return { root: base, project: "nylorun", compose, env: join(base, "stack", ".env") };
+/**
+ * Move the Host roots of nylorun 0.4 (`~/.nylorun/stacks/<name>/`) to `tenants/<name>/`, when
+ * that is free: `stack.json` becomes `tenant.json`, and `NYLORUN_STACK_NAME` becomes
+ * `NYLORUN_TENANT_NAME` in `docker/.env` (and `docker/compose.yaml`, until the next start
+ * rewrites it). `stacks/` goes when empty. They move rather than start fresh because Compose
+ * project names do not change: a fresh Host root under the same name would reuse the old
+ * volumes with new keys.
+ */
+export async function moveStackRoots(base, err) {
+    const stacks = join(base, "stacks");
+    let names;
+    try {
+        names = (await readdir(stacks, { withFileTypes: true }))
+            .filter((entry) => entry.isDirectory() && TENANT_NAME.test(entry.name))
+            .map((entry) => entry.name);
+    }
+    catch {
+        return;
+    }
+    const moved = [];
+    for (const name of names.sort()) {
+        const root = tenantRoot(base, name);
+        if (existsSync(root))
+            continue;
+        await mkdir(tenantsDir(base), { recursive: true, mode: 0o700 });
+        await rename(join(stacks, name), root);
+        await rename(join(root, "stack.json"), tenantRecordPath(root)).catch(() => { });
+        for (const file of [join(root, "docker", ".env"), join(root, "docker", "compose.yaml")]) {
+            const text = await readFile(file, "utf8").catch(() => undefined);
+            if (text?.includes("NYLORUN_STACK_NAME"))
+                await writeFile(file, text.replaceAll("NYLORUN_STACK_NAME", "NYLORUN_TENANT_NAME"));
+        }
+        moved.push(name);
+    }
+    // A marker file of 0.4.
+    await rm(join(stacks, ".legacy-noted"), { force: true });
+    await rmdir(stacks).catch(() => { });
+    if (moved.length) {
+        const tilde = (path) => path.startsWith(homedir() + sep) ? `~${path.slice(homedir().length)}` : path;
+        err(`Moved Tenants ${moved.join(", ")} from ${tilde(stacks)} to ${tilde(tenantsDir(base))}.`);
+    }
 }
-/** What `nylorun legacy delete` removes from `~/.nylorun`: the old layout only, never `stacks/`. */
-export const LEGACY_ENTRIES = [
-    "host.json",
-    "host-credentials.json",
-    "host-state.json",
-    "stack",
-    "tenants",
-    "home",
-    "tmp",
-    "trash",
-];

package/dist/stack/versions.d.ts

@@ -3,7 +3,7 @@ export type PinnedImage = "runtime" | "studio";
 /**
  * The version this CLI release pins for an image, from `cli/package.json`
  * `nylorun.runtime` or `nylorun.studio`: the tag of `ghcr.io/nylorun/<name>`
- * the stack runs unless `NYLORUN_RUNTIME_IMAGE` / `NYLORUN_STUDIO_IMAGE`
+ * a local Tenant runs unless `NYLORUN_RUNTIME_IMAGE` / `NYLORUN_STUDIO_IMAGE`
  * overrides it. The release tooling writes both pins.
  */
 export declare function pinnedVersion(name: PinnedImage): string;

package/dist/stack/versions.js

@@ -9,7 +9,7 @@ function cliPackageJsonPath() {
 /**
  * The version this CLI release pins for an image, from `cli/package.json`
  * `nylorun.runtime` or `nylorun.studio`: the tag of `ghcr.io/nylorun/<name>`
- * the stack runs unless `NYLORUN_RUNTIME_IMAGE` / `NYLORUN_STUDIO_IMAGE`
+ * a local Tenant runs unless `NYLORUN_RUNTIME_IMAGE` / `NYLORUN_STUDIO_IMAGE`
  * overrides it. The release tooling writes both pins.
  */
 export function pinnedVersion(name) {

package/dist/telemetry.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Studio's anonymous usage analytics. Studio's dashboard reports page views,
+ * with every id replaced by `:id`, to this Google Analytics property unless the
+ * developer opted out. `nylorun start` decides and passes the id to the
+ * Studio container (`NYLORUN_STUDIO_ANALYTICS_ID`); Studio never decides itself.
+ */
+export declare const STUDIO_ANALYTICS_ID = "G-K6RPDFH6Q6";
+/** `~/.nylorun/telemetry.json`: the developer's choice, for every Tenant on the machine. */
+export interface TelemetryFile {
+    format: 1;
+    /** False after `nylorun telemetry disable`; absent until a choice is made. */
+    enabled?: boolean;
+    /** When `nylorun start` showed the notice (ISO time); it is shown once. */
+    noticeShown?: string;
+}
+export type TelemetryDecision = Readonly<{
+    enabled: boolean;
+    reason: string;
+}>;
+export declare const TELEMETRY_NOTICE: string;
+export declare function telemetryPath(nylorunRoot: string): string;
+export declare function readTelemetry(nylorunRoot: string): Promise<TelemetryFile>;
+export declare function writeTelemetry(nylorunRoot: string, file: TelemetryFile): Promise<void>;
+/** On unless the environment or the developer's choice turns it off. */
+export declare function telemetryDecision(env: Readonly<Record<string, string | undefined>>, file: TelemetryFile): TelemetryDecision;
+/** `nylorun telemetry [status|enable|disable]`. */
+export declare function telemetryCommand(args: readonly string[], context: {
+    nylorunRoot: string;
+    env: Readonly<Record<string, string | undefined>>;
+    out(line: string): void;
+}): Promise<number>;

package/dist/telemetry.js

@@ -0,0 +1,79 @@
+import { randomBytes } from "node:crypto";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { CliError } from "./errors.js";
+/**
+ * Studio's anonymous usage analytics. Studio's dashboard reports page views,
+ * with every id replaced by `:id`, to this Google Analytics property unless the
+ * developer opted out. `nylorun start` decides and passes the id to the
+ * Studio container (`NYLORUN_STUDIO_ANALYTICS_ID`); Studio never decides itself.
+ */
+export const STUDIO_ANALYTICS_ID = "G-K6RPDFH6Q6";
+export const TELEMETRY_NOTICE = [
+    "Studio collects anonymous usage data: which pages are opened, with every",
+    "Tenant, agent and session id removed. Nothing you send to agents is collected.",
+    'Turn it off with "nylorun telemetry disable" or NYLORUN_TELEMETRY_DISABLED=1.',
+    "Learn more: https://github.com/nylorun/agents/blob/main/nylorun/README.md#telemetry",
+].join("\n");
+export function telemetryPath(nylorunRoot) {
+    return join(nylorunRoot, "telemetry.json");
+}
+export async function readTelemetry(nylorunRoot) {
+    try {
+        const parsed = JSON.parse(await readFile(telemetryPath(nylorunRoot), "utf8"));
+        if (parsed && typeof parsed === "object") {
+            const { enabled, noticeShown } = parsed;
+            return {
+                format: 1,
+                ...(typeof enabled === "boolean" ? { enabled } : {}),
+                ...(typeof noticeShown === "string" ? { noticeShown } : {}),
+            };
+        }
+    }
+    catch {
+        /* missing or unreadable: no choice yet */
+    }
+    return { format: 1 };
+}
+export async function writeTelemetry(nylorunRoot, file) {
+    await mkdir(nylorunRoot, { recursive: true });
+    const path = telemetryPath(nylorunRoot);
+    const temporary = `${path}.${randomBytes(8).toString("hex")}.tmp`;
+    await writeFile(temporary, `${JSON.stringify(file, null, 2)}\n`);
+    await rename(temporary, path);
+}
+/** An environment flag is set unless it is empty, `0`, `false` or `no`. */
+function flag(value) {
+    const trimmed = value?.trim() ?? "";
+    return trimmed !== "" && !/^(0|false|no)$/i.test(trimmed);
+}
+/** On unless the environment or the developer's choice turns it off. */
+export function telemetryDecision(env, file) {
+    if (flag(env.NYLORUN_TELEMETRY_DISABLED))
+        return { enabled: false, reason: "NYLORUN_TELEMETRY_DISABLED is set" };
+    if (flag(env.DO_NOT_TRACK))
+        return { enabled: false, reason: "DO_NOT_TRACK is set" };
+    if (flag(env.CI))
+        return { enabled: false, reason: "CI is set" };
+    if (file.enabled === false)
+        return { enabled: false, reason: 'turned off with "nylorun telemetry disable"' };
+    return { enabled: true, reason: "on by default" };
+}
+const USAGE = "Usage: nylorun telemetry [status|enable|disable]";
+/** `nylorun telemetry [status|enable|disable]`. */
+export async function telemetryCommand(args, context) {
+    const [action = "status", ...rest] = args;
+    if (rest.length || !["status", "enable", "disable"].includes(action))
+        throw new CliError(USAGE, 2);
+    const file = await readTelemetry(context.nylorunRoot);
+    if (action !== "status") {
+        const enabled = action === "enable";
+        await writeTelemetry(context.nylorunRoot, { ...file, enabled });
+        context.out(`Studio telemetry ${enabled ? "enabled" : "disabled"}. Running Tenants pick this up on the next "nylorun start".`);
+    }
+    const decision = telemetryDecision(context.env, await readTelemetry(context.nylorunRoot));
+    context.out(`Studio telemetry is ${decision.enabled ? "on" : "off"} (${decision.reason}).`);
+    if (action === "status")
+        context.out(TELEMETRY_NOTICE);
+    return 0;
+}

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "nylorun",
-  "version": "0.4.0-beta",
+  "version": "0.5.0-beta",
   "type": "module",
   "license": "Apache-2.0",
-  "description": "Set up and run the local Nylorun stack (Runtime and Studio) with Docker Compose",
+  "description": "Set up and run local Nylorun Tenants (Runtime and Studio) with Docker Compose",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nylorun/agents.git",
@@ -30,7 +30,7 @@
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@nylorun/core": "0.10.0-beta"
+    "@nylorun/core": "0.11.0-beta"
   },
   "devDependencies": {
     "typescript": "npm:@typescript/typescript6@^6.0.2",
@@ -41,7 +41,7 @@
     "nylorun": "dist/cli.js"
   },
   "nylorun": {
-    "runtime": "0.15.0-beta",
-    "studio": "0.15.0-beta"
+    "runtime": "0.15.1-beta",
+    "studio": "0.16.0-beta"
   }
 }