rolexjs 1.5.0 → 1.6.1

package/dist/index.d.ts

@@ -1,22 +1,118 @@
-import { Platform, Renderer, RoleXBuilder } from '@rolexjs/core';
+import { Platform } from '@rolexjs/core';
 export * from '@rolexjs/core';
-import { State } from '@rolexjs/system';
+import { State, Structure } from '@rolexjs/system';
+import { Comment, Issue } from 'issuexjs';
+import { Ops } from '@rolexjs/prototype';
+export { world } from '@rolexjs/prototype';
 
 /**
- * Product Render — format product state as readable text.
+ * RoleContext — stateful session context for role operations.
  *
- * Renders product operations into human-readable summaries.
- * Ownership links show owner names only (not full individual trees).
- * Specs show behavior contract titles for quick overview.
+ * Tracks execution state from the individual's perspective:
+ *   - roleId (who I am)
+ *   - focusedGoalId / focusedPlanId (what I'm working on)
+ *   - encounter / experience id sets (what I have for cognition)
+ *
+ * Created by activate, updated by subsequent role operations.
+ * Consumers (MCP, CLI) hold a reference and pass it through.
  */
 
-type ProductAction = "produce" | "strategy" | "spec" | "release" | "channel" | "own" | "disown" | "deprecate";
-declare function renderProduct(state: State): string;
+declare class RoleContext {
+    roleId: string;
+    focusedGoalId: string | null;
+    focusedPlanId: string | null;
+    readonly encounterIds: Set<string>;
+    readonly experienceIds: Set<string>;
+    constructor(roleId: string);
+    requireGoalId(): string;
+    requirePlanId(): string;
+    addEncounter(id: string): void;
+    requireEncounterIds(ids: string[]): void;
+    consumeEncounters(ids: string[]): void;
+    addExperience(id: string): void;
+    requireExperienceIds(ids: string[]): void;
+    consumeExperiences(ids: string[]): void;
+    /** Walk the state tree and populate registries. */
+    rehydrate(state: State): void;
+    private walk;
+    /** First-person, state-aware hint for the AI after an operation. */
+    cognitiveHint(process: string): string | null;
+}
+
 /**
- * Render a product operation result as readable text.
- * Returns status + hint + product overview.
+ * Feature — the information format for the RoleX concept world.
+ *
+ * Every node's information is a Gherkin Feature.
+ * This is our own type — decoupled from @cucumber/messages.
+ */
+interface Feature {
+    readonly name: string;
+    readonly description?: string;
+    readonly tags?: readonly string[];
+    readonly scenarios: readonly Scenario[];
+}
+interface Scenario {
+    readonly name: string;
+    readonly description?: string;
+    readonly tags?: readonly string[];
+    readonly steps: readonly Step[];
+}
+interface Step {
+    readonly keyword: string;
+    readonly text: string;
+    readonly dataTable?: readonly DataTableRow[];
+}
+interface DataTableRow {
+    readonly cells: readonly string[];
+}
+/** Parse a Gherkin source string into a Feature. */
+declare function parse(source: string): Feature;
+/** Serialize a Feature back to Gherkin source string. */
+declare function serialize(feature: Feature): string;
+
+/**
+ * Find — unified node lookup with priority-based disambiguation.
+ *
+ * When multiple nodes share the same id (allowed after relaxing
+ * global uniqueness), prefer "addressable" nodes over internal metadata.
+ *
+ * Priority (lower = preferred):
+ *   0: individual, organization, position   — top-level entities
+ *   1: goal                                  — execution roots
+ *   2: plan, task                            — execution nodes
+ *   3: procedure, principle                  — individual knowledge
+ *   4: encounter, experience                 — cognition artifacts
+ *   5: identity, charter                     — structural definitions
+ *   6: duty, requirement, background, etc.   — internal metadata
  */
-declare function renderProductResult(action: ProductAction, state: State): string;
+
+/**
+ * Find a node by id or alias in a state tree.
+ *
+ * When multiple nodes match, returns the one with the highest priority
+ * (top-level entities > execution nodes > knowledge > metadata).
+ */
+declare function findInState(state: State, target: string): Structure | null;
+
+/**
+ * Issue Render — format IssueX data as readable text.
+ *
+ * Lightweight rendering for issue operations.
+ * Unlike the core render layer (which projects State trees),
+ * this module formats flat IssueX objects into human-readable strings.
+ */
+
+type IssueAction = "publish" | "get" | "list" | "close" | "reopen" | "update" | "assign" | "comment" | "comments" | "label" | "unlabel";
+type LabelResolver = (ids: string[]) => Promise<string[]>;
+declare function renderIssue(issue: Issue, labelNames?: string[]): string;
+declare function renderIssueList(issues: Issue[]): string;
+declare function renderComment(comment: Comment): string;
+declare function renderCommentList(comments: Comment[]): string;
+/**
+ * Render an issue operation result as readable text.
+ * Dispatches to the right renderer based on action.
+ */
+declare function renderIssueResult(action: IssueAction, result: unknown, resolveLabels?: LabelResolver): Promise<string>;
 
 /**
  * Project Render — format project state as readable text.
@@ -26,7 +122,8 @@ declare function renderProductResult(action: ProductAction, state: State): strin
  * Milestones show progress status (#done or pending).
  */
 
-type ProjectAction = "launch" | "scope" | "milestone" | "achieve" | "enroll" | "remove" | "deliver" | "wiki" | "archive" | "produce";
+type ProjectAction = "launch" | "scope" | "milestone" | "achieve" | "enroll" | "remove" | "deliver" | "wiki" | "archive";
+declare function renderProject(state: State): string;
 /**
  * Render a project operation result as readable text.
  * Returns status + hint + project overview.
@@ -34,21 +131,170 @@ type ProjectAction = "launch" | "scope" | "milestone" | "achieve" | "enroll" | "
 declare function renderProjectResult(action: ProjectAction, state: State): string;
 
 /**
- * RoleX — builder entry point.
+ * Render — 3-layer output for all Rolex operations.
+ *
+ * Layer 1: Status     — what just happened (describe)
+ * Layer 2: Hint       — what to do next (hint + cognitive hint)
+ * Layer 3: Projection — full state tree as markdown (renderState)
+ *
+ * render() composes the 3 layers. MCP and CLI are pure pass-through.
+ */
+
+declare function describe(process: string, name: string, state: State): string;
+declare function hint(process: string): string;
+
+/** Full Gherkin feature content for a process — sourced from .feature files. */
+declare function detail(process: string): string;
+
+/** Get a directive by topic and scenario. Returns empty string if not found. */
+declare function directive(topic: string, scenario: string): string;
+/**
+ * renderState — markdown renderer for State trees.
+ *
+ * Rules:
+ *   - Heading: "#" repeated to depth + " [name]"
+ *   - Body: raw information field as-is (full Gherkin preserved)
+ *   - Links: "> → relation [target.name]" with target feature name
+ *   - Children: sorted by concept hierarchy, then rendered at depth+1
+ *   - Fold: when fold(node) returns true, render heading only (no body/links/children)
+ *
+ * Markdown heading depth caps at 6 (######).
+ */
+interface RenderStateOptions {
+    /** When returns true, render only the heading — skip body, links, and children. */
+    fold?: (node: State) => boolean;
+}
+declare function renderState(state: State, depth?: number, options?: RenderStateOptions): string;
+interface RenderOptions {
+    /** The process that was executed. */
+    process: string;
+    /** Display name for the primary node. */
+    name: string;
+    /** State projection of the affected node. */
+    state: State;
+    /** AI cognitive hint — first-person, state-aware self-direction cue. */
+    cognitiveHint?: string | null;
+    /** Fold predicate — folded nodes render heading only. */
+    fold?: RenderStateOptions["fold"];
+}
+/** Render a full 3-layer output string. */
+declare function render(opts: RenderOptions): string;
+
+/**
+ * Role — stateful handle returned by Rolex.activate().
+ *
+ * Holds roleId + RoleContext internally.
+ * All operations return rendered 3-layer text (status + hint + projection).
+ * MCP and CLI are pure pass-through — no render logic needed.
  *
  * Usage:
- *   import { createRoleX } from "rolexjs";
+ *   const role = await rolex.activate("sean");
+ *   await role.want("Feature: Ship v1", "ship-v1");   // → rendered string
+ *   await role.plan("Feature: Phase 1", "phase-1");    // → rendered string
+ *   await role.finish("write-tests", "Feature: Tests written");
+ */
+
+/**
+ * Internal API surface that Role delegates to.
+ * Constructed by Rolex.activate() — not part of public API.
+ */
+interface RolexInternal {
+    ops: Ops;
+    saveCtx(ctx: RoleContext): void | Promise<void>;
+    direct<T>(locator: string, args?: Record<string, unknown>): Promise<T>;
+    resolveLabels?: LabelResolver;
+}
+declare class Role {
+    readonly roleId: string;
+    readonly ctx: RoleContext;
+    private api;
+    constructor(roleId: string, ctx: RoleContext, api: RolexInternal);
+    /** Project the individual's full state tree (used after activate). */
+    project(): Promise<string>;
+    /** Render an OpResult into a 3-layer output string. */
+    private fmt;
+    private save;
+    /** Focus: view or switch focused goal. Only accepts goal ids. */
+    focus(goal?: string): Promise<string>;
+    /** Want: declare a goal. */
+    want(goal?: string, id?: string, alias?: readonly string[]): Promise<string>;
+    /** Plan: create a plan for the focused goal. */
+    plan(plan?: string, id?: string, after?: string, fallback?: string): Promise<string>;
+    /** Todo: add a task to the focused plan. */
+    todo(task?: string, id?: string, alias?: readonly string[]): Promise<string>;
+    /** Finish: complete a task, optionally record an encounter. */
+    finish(task: string, encounter?: string): Promise<string>;
+    /** Complete: close a plan as done, record encounter. */
+    complete(plan?: string, encounter?: string): Promise<string>;
+    /** Abandon: drop a plan, record encounter. */
+    abandon(plan?: string, encounter?: string): Promise<string>;
+    /** Reflect: consume encounters → experience. Empty encounters = direct creation. */
+    reflect(encounters: string[], experience?: string, id?: string): Promise<string>;
+    /** Realize: consume experiences → principle. Empty experiences = direct creation. */
+    realize(experiences: string[], principle?: string, id?: string): Promise<string>;
+    /** Master: create procedure, optionally consuming experiences. */
+    master(procedure: string, id?: string, experiences?: string[]): Promise<string>;
+    /** Forget: remove any node under the individual by id. */
+    forget(nodeId: string): Promise<string>;
+    /** Skill: load full skill content by locator. */
+    skill(locator: string): Promise<string>;
+    /** Use: subjective execution — `!ns.method` or ResourceX locator. */
+    use<T = unknown>(locator: string, args?: Record<string, unknown>): Promise<T>;
+}
+
+/**
+ * Rolex — thin API shell.
+ *
+ * Public API:
+ *   genesis()    — create the world on first run
+ *   activate(id) — returns a stateful Role handle
+ *   direct(loc, args) — direct the world to execute an instruction
  *
- *   const rx = createRoleX({ platform });
- *   const role = await rx.individual.activate({ individual: "sean" });
- *   await rx.society.born({ id: "alice", content: "Feature: Alice" });
+ * All operation implementations live in @rolexjs/prototype (createOps).
+ * Rolex just wires Platform → ops and manages Role lifecycle.
  */
 
-interface RoleXConfig {
-    platform: Platform;
-    renderer?: Renderer;
+/** Summary entry returned by census.list. */
+interface CensusEntry {
+    id?: string;
+    name: string;
+    tag?: string;
+}
+declare class Rolex {
+    private rt;
+    private ops;
+    private resourcex?;
+    private issuex?;
+    private repo;
+    private readonly initializer?;
+    private readonly bootstrap;
+    private society;
+    private past;
+    private constructor();
+    /** Create a Rolex instance from a Platform (async due to Runtime initialization). */
+    static create(platform: Platform): Promise<Rolex>;
+    /** Async initialization — called by Rolex.create(). */
+    private init;
+    /** Genesis — create the world on first run. Settles built-in prototypes. */
+    genesis(): Promise<void>;
+    /**
+     * Activate a role — returns a stateful Role handle.
+     *
+     * If the individual does not exist in runtime but a prototype is registered,
+     * auto-born the individual first.
+     */
+    activate(individual: string): Promise<Role>;
+    /** Find a node by id or alias across the entire society tree. Internal use only. */
+    private find;
+    /**
+     * Direct the world to execute an instruction.
+     *
+     * - `!namespace.method` — dispatch to ops
+     * - anything else — delegate to ResourceX `ingest`
+     */
+    direct<T = unknown>(locator: string, args?: Record<string, unknown>): Promise<T>;
 }
-/** Create a RoleX builder. Synchronous — initialization is lazy. Genesis is built-in. */
-declare function createRoleX(config: RoleXConfig): RoleXBuilder;
+/** Create a Rolex instance from a Platform. */
+declare function createRoleX(platform: Platform): Promise<Rolex>;
 
-export { type ProductAction, type ProjectAction, type RoleXConfig, createRoleX, renderProduct, renderProductResult, renderProjectResult };
+export { type CensusEntry, type DataTableRow, type Feature, type IssueAction, type LabelResolver, type ProjectAction, type RenderOptions, type RenderStateOptions, Role, RoleContext, Rolex, type Scenario, type Step, createRoleX, describe, detail, directive, findInState, hint, parse, render, renderComment, renderCommentList, renderIssue, renderIssueList, renderIssueResult, renderProject, renderProjectResult, renderState, serialize };