@fnndsc/chili 3.2.5

package/docs/32_file_content.adoc

@@ -0,0 +1,471 @@
+= File Content Retrieval in ChILI
+:toc:
+:toc-placement: preamble
+:sectnums:
+
+== Overview
+
+This document describes how ChILI commands and controllers consume the file content retrieval functionality provided by the `salsa` business logic layer. It focuses on the integration patterns used in ChILI's command layer.
+
+For comprehensive architecture and implementation details, see: `salsa/docs/file-content-retrieval.adoc`
+
+== Integration Pattern
+
+ChILI commands follow this pattern:
+
+1. **Parse arguments** - Extract file path from user input
+2. **Resolve path** - Convert relative → absolute using `path_resolveChrisFs()`
+3. **Call salsa** - Invoke `fileContent_get(filePath)`
+4. **Handle result** - Check `Result<T>`, pop errors from `errorStack`
+5. **Display output** - Render content or error message
+
+== Commands Using File Content
+
+=== 1. `cat` Command
+
+**File:** `src/commands/fs/cat.ts`
+
+**Purpose:** Display file content (like Unix `cat`)
+
+[source,typescript]
+----
+import { fileContent_get } from "@fnndsc/salsa";
+import { path_resolveChrisFs } from "../../utils/cli.js";
+import { Result } from "@fnndsc/cumin";
+
+/**
+ * Retrieves the content of a file.
+ *
+ * @param filePath - The path to the file.
+ * @returns Promise resolving to content string or error.
+ */
+export async function files_cat(filePath: string): Promise<Result<string>> {
+  const resolved: string = await path_resolveChrisFs(filePath, {});
+  return await fileContent_get(resolved);
+}
+----
+
+**Key Points:**
+
+* **RPN naming:** Function named `files_cat` (not `catFile` or `getCatContent`)
+* **Path resolution:** Always resolve relative paths before calling salsa
+* **Pass-through:** Returns `Result<T>` directly to caller for error handling
+* **No console output:** Command logic is pure, caller decides how to display
+
+**Usage in CLI:**
+
+[source,bash]
+----
+chili chefs cat /home/user/file.txt
+chili chefs cat ./relative/path.txt
+chili chefs cat /PIPELINES/user/spec.yml
+----
+
+---
+
+=== 2. `view` Command
+
+**File:** `src/commands/file/view.ts`
+
+**Purpose:** View content of a specific file (supports ID or path)
+
+[source,typescript]
+----
+import { fileContent_get } from "@fnndsc/salsa";
+import { Result } from "@fnndsc/cumin";
+
+/**
+ * Fetches the content of a ChRIS file as a UTF-8 string.
+ *
+ * @param fileIdentifier - The path of the file to view.
+ * @returns A Promise resolving to the file content as a string, or `null` if empty/not found.
+ * @throws {Error} If the operation fails and an error is pushed to the stack.
+ */
+export async function files_viewContent(fileIdentifier: string): Promise<string | null> {
+  const result: Result<string> = await fileContent_get(fileIdentifier);
+
+  if (!result.ok) {
+    // Errors are pushed to the stack within salsa
+    throw new Error(`Failed to view content for: ${fileIdentifier}`);
+  }
+
+  return result.value;
+}
+----
+
+**Key Points:**
+
+* **Alternative error handling:** Throws exception instead of returning `Result<T>`
+* **Why?** This function is called by controller layer which expects exceptions
+* **Pattern:** `Result<T>` → exception conversion for legacy compatibility
+
+**Usage in CLI:**
+
+[source,bash]
+----
+chili file view /home/user/data.json
+----
+
+---
+
+=== 3. FileController
+
+**File:** `src/controllers/fileController.ts`
+
+**Purpose:** Controller-level abstraction for file operations
+
+[source,typescript]
+----
+import {
+  fileContent_get,
+  FileShareOptions
+} from "@fnndsc/salsa";
+import { Result, errorStack } from "@fnndsc/cumin";
+import chalk from 'chalk';
+
+export class FileController extends BaseController {
+  /**
+   * Views content of a file using salsa logic.
+   *
+   * @param filePath - The ChRIS path to the file.
+   * @returns A Promise resolving to void (output is logged).
+   */
+  async file_view(filePath: string): Promise<void> {
+    const result: Result<string> = await fileContent_get(filePath);
+    if (!result.ok) {
+        const error = errorStack.stack_pop();
+        console.error(chalk.red(`Error viewing file: ${error?.message || 'Unknown error'}`));
+        return;
+    }
+    console.log(result.value);
+  }
+}
+----
+
+**Key Points:**
+
+* **Controller responsibility:** Handle display/formatting
+* **Error rendering:** Uses `chalk` for colored error messages
+* **Result handling:** Explicit `!result.ok` check, error pop, display
+* **Separation:** Business logic in salsa, presentation in controller
+
+---
+
+== Import Patterns
+
+=== Standard Import
+
+[source,typescript]
+----
+// Named import (preferred)
+import { fileContent_get } from "@fnndsc/salsa";
+
+// Usage
+const result = await fileContent_get(path);
+----
+
+=== Avoiding Conflicts
+
+If you need to import multiple `*_get` functions:
+
+[source,typescript]
+----
+import {
+  fileContent_get,
+  fileFields_get,
+  feedContent_get
+} from "@fnndsc/salsa";
+----
+
+Names are distinct due to RPN convention (subject comes first).
+
+---
+
+== Error Handling Patterns
+
+=== Pattern 1: Return Result<T>
+
+**When:** Command logic that doesn't display output
+
+[source,typescript]
+----
+export async function files_cat(filePath: string): Promise<Result<string>> {
+  const resolved: string = await path_resolveChrisFs(filePath, {});
+  return await fileContent_get(resolved);  // Pass-through
+}
+----
+
+**Caller:**
+[source,typescript]
+----
+const result = await files_cat(path);
+if (!result.ok) {
+  const error = errorStack.stack_pop();
+  console.error(chalk.red(error?.message));
+  return;
+}
+console.log(result.value);
+----
+
+---
+
+=== Pattern 2: Throw Exception
+
+**When:** Integration with legacy code expecting exceptions
+
+[source,typescript]
+----
+export async function files_viewContent(fileId: string): Promise<string | null> {
+  const result: Result<string> = await fileContent_get(fileId);
+
+  if (!result.ok) {
+    throw new Error(`Failed to view content for: ${fileId}`);
+  }
+
+  return result.value;
+}
+----
+
+**Caller:**
+[source,typescript]
+----
+try {
+  const content = await files_viewContent(path);
+  console.log(content);
+} catch (error) {
+  console.error(`Error: ${error.message}`);
+}
+----
+
+---
+
+=== Pattern 3: Display Directly
+
+**When:** Controller methods that handle both logic and display
+
+[source,typescript]
+----
+async file_view(filePath: string): Promise<void> {
+  const result: Result<string> = await fileContent_get(filePath);
+  if (!result.ok) {
+      const error = errorStack.stack_pop();
+      console.error(chalk.red(`Error: ${error?.message}`));
+      return;
+  }
+  console.log(result.value);
+}
+----
+
+== Path Resolution
+
+Always resolve paths before calling salsa functions:
+
+[source,typescript]
+----
+import { path_resolveChrisFs } from "../../utils/cli.js";
+
+// User input (may be relative)
+const userPath = "./data/file.txt";
+
+// Resolve to absolute
+const resolved: string = await path_resolveChrisFs(userPath, {});
+// Result: "/home/chris/data/file.txt"
+
+// Now safe to call salsa
+const result = await fileContent_get(resolved);
+----
+
+**Why?**
+
+* User may provide relative paths
+* Salsa expects absolute paths
+* Path resolution respects current working directory
+
+== Adding New Commands
+
+To add a new command that uses file content:
+
+=== Step 1: Create Command File
+
+[source,typescript]
+----
+// src/commands/mycommand/process.ts
+import { fileContent_get } from "@fnndsc/salsa";
+import { path_resolveChrisFs } from "../../utils/cli.js";
+import { Result } from "@fnndsc/cumin";
+
+/**
+ * Process a file's content.
+ *
+ * @param filePath - Path to the file.
+ * @returns Result with processed content.
+ */
+export async function fileContent_process(filePath: string): Promise<Result<string>> {
+  const resolved: string = await path_resolveChrisFs(filePath, {});
+  const result: Result<string> = await fileContent_get(resolved);
+
+  if (!result.ok) {
+    return result;  // Pass through error
+  }
+
+  // Process content
+  const processed: string = result.value.toUpperCase();  // Example
+  return Ok(processed);
+}
+----
+
+=== Step 2: Add CLI Handler
+
+[source,typescript]
+----
+// src/index.ts or appropriate CLI router
+import { fileContent_process } from './commands/mycommand/process.js';
+
+// In command handler
+case 'process':
+  const result = await fileContent_process(args.file);
+  if (!result.ok) {
+    const error = errorStack.stack_pop();
+    console.error(chalk.red(error?.message));
+  } else {
+    console.log(result.value);
+  }
+  break;
+----
+
+=== Step 3: Add Tests
+
+[source,typescript]
+----
+// tests/mycommand.test.ts
+import { fileContent_process } from '../src/commands/mycommand/process';
+
+describe('fileContent_process', () => {
+  it('should process file content', async () => {
+    // Mock fileContent_get
+    const result = await fileContent_process('/test/file.txt');
+    expect(result.ok).toBe(true);
+  });
+});
+----
+
+== Testing
+
+=== Mocking File Content
+
+[source,typescript]
+----
+import { fileContent_get } from "@fnndsc/salsa";
+
+// Mock in test setup
+jest.mock('@fnndsc/salsa', () => ({
+  fileContent_get: jest.fn()
+}));
+
+// In test
+const mockFileContent = fileContent_get as jest.MockedFunction<typeof fileContent_get>;
+mockFileContent.mockResolvedValue({
+  ok: true,
+  value: 'mock file content'
+});
+
+// Test your command
+const result = await files_cat('/test/file.txt');
+expect(result.ok).toBe(true);
+expect(result.value).toBe('mock file content');
+----
+
+== Debugging
+
+=== Enable Verbose Logging
+
+Temporarily add logging in commands:
+
+[source,typescript]
+----
+export async function files_cat(filePath: string): Promise<Result<string>> {
+  console.error(`[DEBUG] files_cat called with: ${filePath}`);
+
+  const resolved: string = await path_resolveChrisFs(filePath, {});
+  console.error(`[DEBUG] Resolved to: ${resolved}`);
+
+  const result = await fileContent_get(resolved);
+  console.error(`[DEBUG] Result ok: ${result.ok}`);
+
+  return result;
+}
+----
+
+**Remember to remove debug statements before committing.**
+
+=== Check Error Stack
+
+If errors are unclear:
+
+[source,typescript]
+----
+const result = await fileContent_get(path);
+if (!result.ok) {
+  // Pop ALL errors to see full stack
+  while (true) {
+    const error = errorStack.stack_pop();
+    if (!error) break;
+    console.error(`[${error.level}] ${error.message}`);
+  }
+}
+----
+
+== Common Issues
+
+[cols="2,3,3"]
+|===
+| Issue | Cause | Solution
+
+| **Relative path fails**
+| Path not resolved
+| Use `path_resolveChrisFs()` before calling salsa
+
+| **Error not displayed**
+| Forgot to pop errorStack
+| Always `errorStack.stack_pop()` after `Err()`
+
+| **Pipeline files fail**
+| Wrong path format
+| Ensure path starts with `/PIPELINES/`
+
+| **File not found**
+| Typo or permissions
+| Test with `chili chefs ls` first
+|===
+
+== Performance Tips
+
+1. **Don't fetch unnecessarily**
+   - Check if file exists with `ls` before `cat`
+   - Cache results if displaying multiple times
+
+2. **Large files**
+   - Consider streaming for files > 10MB
+   - Warn user before fetching huge files
+
+3. **Batch operations**
+   - Use `Promise.all()` for multiple files
+   - But respect API rate limits
+
+== Related Documentation
+
+* **Comprehensive Architecture:** `salsa/docs/file-content-retrieval.adoc`
+* **VFS Routing:** `chell/docs/vfs.adoc`
+* **Error Handling:** `cumin/docs/error_handling.adoc`
+* **RPN Naming:** `TYPESCRIPT-STYLE-GUIDE.md`
+
+== Change Log
+
+[cols="1,2,4"]
+|===
+| Version | Date | Changes
+
+| 1.0.0
+| 2025-12-09
+| Initial chili integration documentation
+|===

package/docs/_architecture.adoc

@@ -0,0 +1,48 @@
+= ChUI Architecture: The "Command as Library" Model
+
+== Introduction
+
+The ChUI (ChRIS User Interface) codebase, encompassing `chili`, `salsa`, and `cumin`, follows a strict layered "Sandwich" architecture. This design decouples business logic from presentation, enabling the core functionality to be consumed by multiple frontends—specifically the `chili` CLI and the `chell` interactive shell.
+
+== Core Principles
+
+. **Single Source of Truth:** `chili` commands serve as the definitive implementation for app-level logic.
+. **Separation of Concerns:** Logic (`salsa`), Control (`chili commands`), and Presentation (`chili views`) are distinct.
+. **Pervasive Typing:** Data exchange between layers is governed by strict TypeScript interfaces (Models).
+
+== The Layered "Sandwich" Model
+
+The architecture is composed of three primary layers:
+
+[cols="1,3"]
+|===
+| Layer | Responsibility
+
+| *`chili`* (Controller & View)
+| The top layer is split into sub-layers:
+  * **Commands (`commands/`)**: Headless controllers that call `salsa` and return strictly typed **Models**. They are UI-agnostic and consumable by `chell`.
+  * **Views (`views/`)**: Pure functions that accept Models and return formatted strings/tables.
+  * **Handlers (`handlers/` & `chefs/`)**: The CLI entry points. They parse arguments, invoke Commands, and pass the results to Views.
+  * **Models (`models/`)**: TypeScript interfaces (`src/models/`) defining the data structures exchanged between layers.
+
+| *`salsa`* (Business Logic)
+| The core, reusable library of "Intents". It contains the "how" for every action (e.g., `feed_create`, `files_uploadPath`). This layer wraps `cumin` and returns raw data or success status.
+
+| *`cumin`* (Infrastructure)
+| The lowest-level library that manages state, connectivity, and raw I/O. It provides `IStorageProvider` abstractions for filesystem access (Node vs Browser) and `ChrisIO` for recursive operations.
+|===
+
+== Data Flow Example: `ls`
+
+When a user runs `ls` (in CLI or Shell):
+
+1.  **CLI/Shell**: Calls `chili/commands/fs/ls.ts`.
+2.  **Command**: Calls `salsa/files/index.ts` (`files_listAll`).
+3.  **Salsa**: Calls `cumin` to fetch data from CUBE.
+4.  **Salsa**: Returns raw data to Command.
+5.  **Command**: Maps raw data to `ListingItem[]` Model. Returns Model.
+6.  **CLI/Shell**: Passes `ListingItem[]` to `chili/views/ls.ts` (`renderGrid` or `renderLong`).
+7.  **View**: Returns formatted string.
+8.  **CLI/Shell**: Prints string to stdout.
+
+This ensures `chell` and `chili` behave identically.

package/docs/_deepContext.adoc

@@ -0,0 +1,84 @@
+= Architecture of Context-Driven Resource Resolution
+:toc: left
+:toclevels: 3
+
+This document details the core architectural pattern that powers ChILI and Salsa: **Context-Driven Resource Resolution**. This mechanism allows the application to dynamically resolve and interact with nested API resources based on a persistent session state, decoupling the CLI commands from the hierarchical structure of the REST API.
+
+== The Challenge
+
+The ChRIS REST API is hierarchical. To access a specific resource, you often need to traverse a path:
+`GET /api/v1/plugins/14/parameters/`
+
+In a traditional CLI, this would require repetitive arguments:
+`chili parameters list --plugin 14`
+
+If a user is performing multiple operations on Plugin 14, repeating `--plugin 14` is tedious. Furthermore, different resources (Files, Feed Notes, Plugin Instances) share this "child-of-parent" pattern but have completely different API endpoints and types. Hardcoding handlers for each would violate DRY (Don't Repeat Yourself) principles.
+
+== The Solution: Dynamic Object Contexts
+
+We solve this by abstracting the interaction into three layers:
+
+1.  **State Persistence (`chrisContext`)**: Stores the "ID" or "Path" of the current parent object (e.g., `plugin:14`).
+2.  **The Registry (`ObjContexts`)**: Maps abstract resource names to API methods.
+3.  **The Factory (`objContext_create`)**: Dynamically instantiates a resource manager for the current state.
+
+=== 1. The Registry (`ObjContexts`)
+
+Located in `cumin/src/resources/chrisObjContext.ts`, this registry defines the "universe" of context-aware resources. It maps a generic `type` string to the specific method required to fetch that collection from a parent.
+
+[source,typescript]
+----
+const ObjContexts = {
+  ParametersOfPlugin: {
+    name: "ParametersOfPlugin",
+    getMethod: "getPluginParameters", // The API method to call on the parent
+    contextType: "plugin",            // The type of parent required
+  },
+  ChRISFilesContext: {
+    name: "Files",
+    getMethod: "getFiles",
+    contextType: "folder",
+  },
+  // ...
+};
+----
+
+=== 2. The Factory (`objContext_create`)
+
+This function acts as the bridge between the persistent state and the live API.
+
+1.  It accepts a **Type** (e.g., `"ParametersOfPlugin"`) and a **Context String** (e.g., `"plugin:14"`).
+2.  It parses the context string to extract the ID (`14`).
+3.  It fetches the *Parent Object* (Plugin 14) from the API.
+4.  It returns a `ChRISEmbeddedResourceGroup` bound to that parent.
+
+This generic group object exposes standard methods (`list`, `search`) that the CLI handlers consume, completely unaware of whether they are listing "files in a folder" or "parameters of a plugin."
+
+== Data Flow Example
+
+When a user runs:
+`chili parametersofplugin list`
+
+The flow is:
+
+1.  **CLI Handler**: `PluginContextGroupHandler` is invoked.
+2.  **Context Lookup**: It asks `chrisContext`: "What is the current plugin?" -> Returns `14`.
+3.  **Controller**: `PluginContextController` calls the factory:
+    `objContext_create("ParametersOfPlugin", "plugin:14")`
+4.  **Factory**:
+    *   Looks up `ParametersOfPlugin` in registry.
+    *   Fetches Plugin `14`.
+    *   Returns a group object bound to `plugin.getPluginParameters()`.
+5.  **BaseHandler**: Calls `.list()` on the group and displays the results.
+
+== Extensibility
+
+This architecture allows for rapid expansion. To support a new nested resource (e.g., "Comments on a Feed"):
+
+1.  Add an entry to `ObjContexts` in `cumin`:
+    ```typescript
+    FeedComments: { getMethod: 'getComments', contextType: 'feed' }
+    ```
+2.  Register a command in `chili` that calls the factory with `"FeedComments"`.
+
+No new logic for listing, filtering, or displaying data is required. The system handles it generically.

package/docs/_roadmap.adoc

@@ -0,0 +1,42 @@
+= ChILI Project Roadmap & Architecture Vision
+:toc: left
+:toclevels: 2
+:doctype: book
+
+== The Sandwich Model: Architecture Overview
+
+The ChRIS Interactive Line Interface (ChILI) project is evolving towards a robust, layered architecture, often referred to as the "Sandwich Model" or Clean Architecture. This design ensures modularity, testability, and reusability across various platforms (CLI, Web, Mobile).
+
+=== Layers of the Sandwich
+
+*   *Top Layer (Interface/Presentation)*:
+    **`chili`**: The Command Line Interface (CLI) application itself. Its primary responsibility is to parse user input (commands, flags), format output for the console, and dispatch actions to the underlying logic layer. It is the CLI analogue of a React or Angular frontend.
+    **`chell` (Future)**: An interactive REPL (Read-Eval-Print Loop) providing a shell-like experience to ChRIS users. It will offer Unix-like commands (`ls`, `cd`, `pwd`) and interactive sessions. This is a future evolution of `chili`.
+
+*   *Middle Layer (Application Logic/Services)*:
+    **`salsa`**: Shared Application Logic and Service Assets. This layer encapsulates the high-level business logic and "intents" (e.g., `feed_create`, `plugin_run`, `files_getGroup`). It acts as a platform-agnostic facade, abstracting away the intricacies of interacting with the ChRIS backend. `salsa` is designed to be reusable by `chili` (and `chell`), web frontends, or any other application consuming ChRIS functionality.
+
+*   *Bottom Layer (Infrastructure/Primitives)*:
+    **`cumin`**: A utility library providing lower-level primitives, state management (token handling, context), and a high-level, object-oriented API for interacting with the ChRIS system. `cumin` abstracts away the direct API calls.
+    **`@fnndsc/chrisapi`**: The foundational, low-level client library that makes direct REST API calls to the ChRIS server. `cumin` wraps and manages this client.
+
+This layered approach enables independent development and evolution of each part, making the system more maintainable and adaptable.
+
+== Future Vision: Chell - The ChRIS Holistic Layer of Logic
+
+Our ultimate goal is to evolve the ChILI experience into a full-fledged interactive shell, tentatively named *Chell*.
+
+=== Chell's Purpose
+
+*   **Holistic Interaction**: Provide a seamless and intuitive environment for users to manage ChRIS resources.
+*   **Unix-like Familiarity**: Offer commands that feel natural to users accustomed to shell environments (`ls`, `cd`, `pwd`, `cp`, `mv`).
+*   **Interactive Context**: Maintain session state, allowing users to navigate the ChRIS filesystem and interact with resources dynamically.
+
+=== Role of 'chefs'
+
+The newly created `chefs` module within `chili` is the initial step towards realizing the *Chell* vision. It serves as the primitive layer for shell-like filesystem commands:
+
+*   **`chili chefs ls`**: Provides a `ls`-like output for ChRIS files and directories.
+*   **`chili chefs mkdir`**: Future command for creating directories (e.g., within feeds).
+
+`chefs` directly utilizes `salsa`'s high-level file management functions, demonstrating how `salsa` serves as the core logic provider for even specialized interface layers like a shell.