@phnx-labs/agents-cli 1.14.2 → 1.14.3

package/dist/lib/rules/compose.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Rules composition — assemble a fully-inlined rules document from layered
+ * `subrules/` fragments and `rules.yaml` preset definitions.
+ *
+ * The model:
+ *   - Every DotAgents repo holds `<repo>/rules/subrules/*.md` (rule fragments)
+ *     and `<repo>/rules/rules.yaml` (preset definitions).
+ *   - Layers are read in precedence order (highest first):
+ *       project > user > extra > system.
+ *   - The active preset's `subrules:` list is resolved against the layer set
+ *     using per-name shadowing — a project subrule shadows a user/system one
+ *     of the same name.
+ *   - Subrules in the user / extra / project layers that the preset did NOT
+ *     name are auto-appended in precedence order. (System auto-append is
+ *     opt-in only: system never auto-appends to avoid noise.)
+ *   - Output is a single concatenated string with no `@-import` syntax.
+ *
+ * No filesystem writes happen here — callers (`syncResourcesToVersion`,
+ * project-rules compile) decide where to land the composed output.
+ */
+export type LayerScope = 'project' | 'user' | 'extra' | 'system';
+export interface RulesLayer {
+    scope: LayerScope;
+    rulesDir: string;
+    /** Set when scope is 'extra'; undefined otherwise. */
+    alias?: string;
+}
+export interface PresetDef {
+    /** Subrule names (without `.md`), in concatenation order. */
+    subrules: string[];
+}
+export interface RulesYaml {
+    presets?: Record<string, PresetDef>;
+}
+export interface ComposeOptions {
+    /** Defaults to `"default"`. */
+    preset?: string;
+    /** Layers in precedence order, highest first. */
+    layers: RulesLayer[];
+}
+export interface ComposedSubrule {
+    name: string;
+    sourcePath: string;
+    layerScope: LayerScope;
+    layerAlias?: string;
+}
+export interface ComposeResult {
+    /** Fully concatenated, no @-imports. */
+    content: string;
+    /** The preset name that was applied. */
+    preset: string;
+    /** The layer that defined the preset. */
+    presetLayer: LayerScope;
+    /** Subrules included, in concatenation order. */
+    subrules: ComposedSubrule[];
+}
+/**
+ * Compose a rules document from the given layers.
+ *
+ * Throws when the requested preset isn't defined in any layer's rules.yaml —
+ * means the caller passed a typo or no layer ships the named preset.
+ */
+export declare function composeRules(opts: ComposeOptions): ComposeResult;
+/**
+ * Discover layers for use at sync time (no cwd) or runtime (with cwd).
+ *
+ * Project layer is included only when cwd is given AND `<cwd>/.agents/rules/`
+ * exists. Without cwd, only user / extras / system are surfaced — matching
+ * the home-file write at sync time.
+ */
+export declare function discoverRulesLayers(opts?: {
+    cwd?: string;
+}): RulesLayer[];
+/** Convenience wrapper — discovers layers from state, then composes. */
+export declare function composeRulesFromState(opts?: {
+    preset?: string;
+    cwd?: string;
+}): ComposeResult;

package/dist/lib/rules/compose.js

@@ -0,0 +1,170 @@
+/**
+ * Rules composition — assemble a fully-inlined rules document from layered
+ * `subrules/` fragments and `rules.yaml` preset definitions.
+ *
+ * The model:
+ *   - Every DotAgents repo holds `<repo>/rules/subrules/*.md` (rule fragments)
+ *     and `<repo>/rules/rules.yaml` (preset definitions).
+ *   - Layers are read in precedence order (highest first):
+ *       project > user > extra > system.
+ *   - The active preset's `subrules:` list is resolved against the layer set
+ *     using per-name shadowing — a project subrule shadows a user/system one
+ *     of the same name.
+ *   - Subrules in the user / extra / project layers that the preset did NOT
+ *     name are auto-appended in precedence order. (System auto-append is
+ *     opt-in only: system never auto-appends to avoid noise.)
+ *   - Output is a single concatenated string with no `@-import` syntax.
+ *
+ * No filesystem writes happen here — callers (`syncResourcesToVersion`,
+ * project-rules compile) decide where to land the composed output.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as yaml from 'yaml';
+import { getResolvedRulesDir, getUserRulesDir, getProjectAgentsDir, getEnabledExtraRepos, } from '../state.js';
+const SUBRULES_DIR_NAME = 'subrules';
+const RULES_YAML_NAME = 'rules.yaml';
+const DEFAULT_PRESET = 'default';
+const SUBRULES_README = 'README.md';
+function readRulesYaml(rulesDir) {
+    const p = path.join(rulesDir, RULES_YAML_NAME);
+    if (!fs.existsSync(p))
+        return null;
+    try {
+        const parsed = yaml.parse(fs.readFileSync(p, 'utf-8'));
+        return parsed || {};
+    }
+    catch {
+        return null;
+    }
+}
+function resolvePreset(layers, preset) {
+    for (const layer of layers) {
+        const yml = readRulesYaml(layer.rulesDir);
+        if (!yml?.presets)
+            continue;
+        const def = yml.presets[preset];
+        if (def)
+            return { def, layer };
+    }
+    return null;
+}
+function findSubrule(layers, name) {
+    for (const layer of layers) {
+        const p = path.join(layer.rulesDir, SUBRULES_DIR_NAME, `${name}.md`);
+        if (fs.existsSync(p))
+            return { sourcePath: p, layer };
+    }
+    return null;
+}
+function listLayerSubruleNames(layer) {
+    const dir = path.join(layer.rulesDir, SUBRULES_DIR_NAME);
+    if (!fs.existsSync(dir))
+        return [];
+    try {
+        return fs
+            .readdirSync(dir)
+            .filter((f) => f.endsWith('.md') && f !== SUBRULES_README)
+            .map((f) => f.slice(0, -3))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Compose a rules document from the given layers.
+ *
+ * Throws when the requested preset isn't defined in any layer's rules.yaml —
+ * means the caller passed a typo or no layer ships the named preset.
+ */
+export function composeRules(opts) {
+    const presetName = opts.preset || DEFAULT_PRESET;
+    const presetMatch = resolvePreset(opts.layers, presetName);
+    if (!presetMatch) {
+        throw new Error(`Preset "${presetName}" not found in any rules.yaml across the active layers.`);
+    }
+    const composed = [];
+    const seen = new Set();
+    // 1. Preset's named subrules, resolved by per-name shadowing.
+    for (const name of presetMatch.def.subrules || []) {
+        if (seen.has(name))
+            continue;
+        const found = findSubrule(opts.layers, name);
+        if (!found)
+            continue; // missing subrule: skip silently — same as @-import miss
+        composed.push({
+            name,
+            sourcePath: found.sourcePath,
+            layerScope: found.layer.scope,
+            layerAlias: found.layer.alias,
+        });
+        seen.add(name);
+    }
+    // 2. Auto-append: any subrule in a non-system layer not yet included.
+    //    Honors precedence — project layer's auto-appends come first.
+    for (const layer of opts.layers) {
+        if (layer.scope === 'system')
+            continue;
+        for (const name of listLayerSubruleNames(layer)) {
+            if (seen.has(name))
+                continue;
+            composed.push({
+                name,
+                sourcePath: path.join(layer.rulesDir, SUBRULES_DIR_NAME, `${name}.md`),
+                layerScope: layer.scope,
+                layerAlias: layer.alias,
+            });
+            seen.add(name);
+        }
+    }
+    // 3. Concatenate. Trim trailing whitespace on each fragment so spacing is
+    //    predictable — fragments often end in a newline already.
+    const parts = composed.map((c) => fs.readFileSync(c.sourcePath, 'utf-8').replace(/\s+$/, ''));
+    const content = parts.length === 0 ? '' : parts.join('\n\n') + '\n';
+    return {
+        content,
+        preset: presetName,
+        presetLayer: presetMatch.layer.scope,
+        subrules: composed,
+    };
+}
+/**
+ * Discover layers for use at sync time (no cwd) or runtime (with cwd).
+ *
+ * Project layer is included only when cwd is given AND `<cwd>/.agents/rules/`
+ * exists. Without cwd, only user / extras / system are surfaced — matching
+ * the home-file write at sync time.
+ */
+export function discoverRulesLayers(opts = {}) {
+    const layers = [];
+    if (opts.cwd) {
+        const projectAgentsDir = getProjectAgentsDir(opts.cwd);
+        if (projectAgentsDir) {
+            const rulesDir = path.join(projectAgentsDir, 'rules');
+            if (fs.existsSync(rulesDir)) {
+                layers.push({ scope: 'project', rulesDir });
+            }
+        }
+    }
+    const userRulesDir = getUserRulesDir();
+    if (fs.existsSync(userRulesDir)) {
+        layers.push({ scope: 'user', rulesDir: userRulesDir });
+    }
+    for (const extra of getEnabledExtraRepos()) {
+        const rulesDir = path.join(extra.dir, 'rules');
+        if (fs.existsSync(rulesDir)) {
+            layers.push({ scope: 'extra', rulesDir, alias: extra.alias });
+        }
+    }
+    const systemRulesDir = getResolvedRulesDir();
+    if (fs.existsSync(systemRulesDir)) {
+        layers.push({ scope: 'system', rulesDir: systemRulesDir });
+    }
+    return layers;
+}
+/** Convenience wrapper — discovers layers from state, then composes. */
+export function composeRulesFromState(opts = {}) {
+    const layers = discoverRulesLayers({ cwd: opts.cwd });
+    return composeRules({ preset: opts.preset, layers });
+}

package/dist/lib/{memory.d.ts → rules/rules.d.ts}

@@ -6,7 +6,7 @@
  * GEMINI.md, etc.). This module handles reading, managing includes, and
  * refreshing rules files across version homes.
  */
-import type { AgentId } from './types.js';
+import type { AgentId } from '../types.js';
 export type InstructionsScope = 'user' | 'project';
 export interface InstalledInstructions {
     agentId: AgentId;
@@ -23,7 +23,7 @@ export interface DiscoveredInstructions {
  * Central rules filename constant.
  * All agents map to this file in ~/.agents/rules/, renamed per-agent when synced.
  */
-export declare const CENTRAL_MEMORY_FILENAME = "AGENTS.md";
+export declare const CENTRAL_RULES_FILENAME = "AGENTS.md";
 /**
  * Get the canonical central rules filename for an agent's instructionsFile.
  * Central storage uses AGENTS.md, which gets renamed per-agent when syncing:
@@ -32,12 +32,12 @@ export declare const CENTRAL_MEMORY_FILENAME = "AGENTS.md";
  *   - Cursor: AGENTS.md → .cursorrules
  *   - Codex/OpenCode: AGENTS.md → AGENTS.md (no rename)
  */
-export declare function getCentralMemoryFileName(agentId: AgentId): string;
+export declare function getCentralRulesFileName(agentId: AgentId): string;
 export declare function getInstructionsPath(agentId: AgentId, scope: InstructionsScope, cwd?: string): string;
 export declare function instructionsExists(agentId: AgentId, scope?: InstructionsScope, cwd?: string): boolean;
 export declare function discoverInstructionsFromRepo(repoPath: string): DiscoveredInstructions[];
 export declare function resolveInstructionsSource(repoPath: string, agentId: AgentId): string | null;
-export declare function discoverMemoryFilesFromRepo(repoPath: string): string[];
+export declare function discoverRuleFilesFromRepo(repoPath: string): string[];
 export declare function installInstructions(sourcePath: string, agentId: AgentId, method?: 'symlink' | 'copy'): {
     path: string;
     method: 'symlink' | 'copy';
@@ -60,4 +60,4 @@ export declare function installInstructionsCentrally(repoPath: string, filesToIn
 /**
  * List top-level rules files from user and system dirs (user wins on collision).
  */
-export declare function listCentralMemory(): string[];
+export declare function listCentralRules(): string[];

package/dist/lib/{memory.js → rules/rules.js}

@@ -8,14 +8,14 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
-import { AGENTS, ALL_AGENT_IDS } from './agents.js';
-import { getResolvedRulesDir, getUserRulesDir, getProjectAgentsDir } from './state.js';
-import { getEffectiveHome } from './versions.js';
+import { AGENTS, ALL_AGENT_IDS } from '../agents.js';
+import { getResolvedRulesDir, getUserRulesDir, getProjectAgentsDir } from '../state.js';
+import { getEffectiveHome } from '../versions.js';
 /**
  * Central rules filename constant.
  * All agents map to this file in ~/.agents/rules/, renamed per-agent when synced.
  */
-export const CENTRAL_MEMORY_FILENAME = 'AGENTS.md';
+export const CENTRAL_RULES_FILENAME = 'AGENTS.md';
 const RULES_DOC_FILENAME = 'README.md';
 function isSyncableRuleMarkdown(filename) {
     return filename.endsWith('.md') && filename !== RULES_DOC_FILENAME;
@@ -46,14 +46,14 @@ function listRuleMarkdownFiles(rulesDir) {
  *   - Cursor: AGENTS.md → .cursorrules
  *   - Codex/OpenCode: AGENTS.md → AGENTS.md (no rename)
  */
-export function getCentralMemoryFileName(agentId) {
+export function getCentralRulesFileName(agentId) {
     const agent = AGENTS[agentId];
     const instrFile = agent.instructionsFile;
     // If it contains a path separator, extract just the filename
     const filename = instrFile.includes('/') ? path.basename(instrFile) : instrFile;
     // If the agent's instructionsFile isn't AGENTS.md, it was renamed FROM AGENTS.md
-    if (filename !== CENTRAL_MEMORY_FILENAME) {
-        return CENTRAL_MEMORY_FILENAME;
+    if (filename !== CENTRAL_RULES_FILENAME) {
+        return CENTRAL_RULES_FILENAME;
     }
     return filename;
 }
@@ -75,7 +75,7 @@ export function getInstructionsPath(agentId, scope, cwd = process.cwd()) {
     const projectAgentsDir = getProjectAgentsDir(cwd);
     if (projectAgentsDir) {
         const projectRulesDir = path.join(projectAgentsDir, 'rules');
-        const centralName = getCentralMemoryFileName(agentId);
+        const centralName = getCentralRulesFileName(agentId);
         const candidates = [
             path.join(projectRulesDir, centralName),
             path.join(projectRulesDir, agent.instructionsFile),
@@ -142,7 +142,7 @@ export function resolveInstructionsSource(repoPath, agentId) {
     }
     return null;
 }
-export function discoverMemoryFilesFromRepo(repoPath) {
+export function discoverRuleFilesFromRepo(repoPath) {
     const rulesDir = path.join(repoPath, 'rules');
     if (!fs.existsSync(rulesDir)) {
         return [];
@@ -283,7 +283,7 @@ export function installInstructionsCentrally(repoPath, filesToInstall) {
 /**
  * List top-level rules files from user and system dirs (user wins on collision).
  */
-export function listCentralMemory() {
+export function listCentralRules() {
     const seen = new Set();
     for (const dir of [getUserRulesDir(), getResolvedRulesDir()]) {
         if (!fs.existsSync(dir))

package/dist/lib/secrets/bundles.d.ts

@@ -1,23 +1,53 @@
 /**
  * Secret bundles -- named sets of keychain-backed environment variables.
  *
- * Each bundle is a YAML file in ~/.agents/secrets/ declaring key names.
- * Values live in the macOS Keychain and are injected into the agent's
- * environment at spawn time via `agents run --secrets <bundle>`.
+ * Bundle metadata (name, description, vars map) is stored in the macOS
+ * Keychain as a JSON blob under `agents-cli.bundles.<name>`. Bundles created
+ * with `--icloud-sync` write the metadata to the iCloud-synced keychain so
+ * the full bundle definition (not just secret values) propagates across
+ * the user's Macs. Nothing about secrets ever lives in plaintext on disk.
+ *
+ * Secret values keep their old layout: one keychain item per key under
+ * `agents-cli.secrets.<bundle>.<key>`, sync-state matching the bundle's
+ * `icloud_sync` flag.
  */
 import { type BundleValue, type SecretRef } from './index.js';
+/** Allowed values for a secret's `type` metadata field. */
+export declare const SECRET_TYPES: readonly ["api-key", "token", "password", "url", "database-url", "ssh-key", "certificate", "webhook", "note"];
+export type SecretType = typeof SECRET_TYPES[number];
+/** Per-secret metadata. All fields optional; absent ones omitted at write time. */
+export interface VarMeta {
+    type?: SecretType;
+    /** ISO date 'YYYY-MM-DD'. Always future-dated at write time. */
+    expires?: string;
+    /** Singular freeform note. */
+    note?: string;
+}
 /** A named set of environment variable definitions backed by various secret providers. */
 export interface SecretsBundle {
     name: string;
     description?: string;
     allow_exec?: boolean;
-    /** When true, keychain-backed values are stored in iCloud Keychain so they sync across the user's Macs. */
+    /** When true, keychain-backed values and bundle metadata sync via iCloud Keychain. */
     icloud_sync?: boolean;
     vars: Record<string, BundleValue>;
+    /** Optional per-var metadata, keyed by var name (parallel to `vars`). */
+    meta?: Record<string, VarMeta>;
 }
+export declare const RESERVED_ENV_NAMES: Set<string>;
+export declare function bundleToEnvPrefix(name: string): string;
+export declare function isReservedEnvName(key: string): boolean;
 /** Validate a bundle name against the allowed pattern. Throws on invalid input. */
 export declare function validateBundleName(name: string): void;
 export declare function validateEnvKey(key: string): void;
+/** Assert that `t` is one of the known SECRET_TYPES. Throws with the allowed list otherwise. */
+export declare function validateSecretType(t: string): asserts t is SecretType;
+/**
+ * Validate an `expires` value. Accepts strict 'YYYY-MM-DD' only and rejects
+ * any date <= now. We compare against end-of-day UTC for the chosen date so
+ * "today" is treated as past (per spec).
+ */
+export declare function validateExpiresFutureDated(iso: string): void;
 export declare function bundleExists(name: string): boolean;
 export declare function readBundle(name: string): SecretsBundle;
 export declare function writeBundle(bundle: SecretsBundle): void;
@@ -31,9 +61,36 @@ export interface BundleEntryInfo {
 export declare function describeBundle(bundle: SecretsBundle): BundleEntryInfo[];
 export declare function resolveBundleEnv(bundle: SecretsBundle): Record<string, string>;
 export declare function keychainRef(key: string): string;
+/** Options for rotateBundleSecret. */
+export interface RotateOptions {
+    /** New plaintext value to write into keychain (replaces the old one). */
+    newValue: string;
+    /** When true, drop existing meta for this key. Mutually exclusive with `meta`. */
+    clearMeta?: boolean;
+    /** Patch to merge into existing meta. Undefined fields preserve current values. */
+    meta?: Partial<VarMeta>;
+}
+/**
+ * Rotate a keychain-backed secret in `bundle`. Errors if `key` is not present
+ * in the bundle (use `add` to introduce a new key). Preserves existing meta
+ * unless `clearMeta` or a `meta` patch is supplied.
+ */
+export declare function rotateBundleSecret(bundle: SecretsBundle, key: string, opts: RotateOptions): void;
 export declare function keychainItemsForBundle(bundle: SecretsBundle): Array<{
     key: string;
     item: string;
 }>;
 export declare function parseDotenv(content: string): Record<string, string>;
+/**
+ * One-shot migration: move legacy YAML bundles into the keychain. Scans both
+ * `~/.agents/secrets/` and `~/.agents-system/secrets/` — past versions of the
+ * CLI sometimes wrote bundles into the system repo even though that's never
+ * been a legitimate location. After migration the directories are removed so
+ * the system repo never carries a `secrets/` subdir again.
+ *
+ * Idempotent: re-runs after the dirs are gone are no-ops. Called eagerly at
+ * the top of every `agents secrets` subcommand. Skipped on the latency-
+ * sensitive `agents run` path.
+ */
+export declare function migrateLegacyBundles(): void;
 export type { SecretRef };