function11 1.0.0

package/README.md

@@ -0,0 +1,366 @@
+# The Function11 Manual
+
+**fn — The Completed U*IX**
+
+---
+
+## 1. Overview
+
+**Function11 (fn)** is a minimalist operating shell and control system designed for:
+
+* secure system administration,
+* human–AI collaboration,
+* elimination of supply-chain risk,
+* complete transparency of execution.
+
+fn replaces:
+
+* traditional shells,
+* Model Context Protocol (MCP),
+* opaque AI tool-calling systems,
+
+with a **single, file-oriented, command-driven environment** inspired by UNIX, Plan 9, and early X systems.
+
+Function11 is not a framework.
+It is not a package ecosystem.
+It is a **system substrate**.
+
+---
+
+## 2. Core Principles
+
+Function11 obeys five axioms:
+
+1. **Everything is a command**
+2. **Every interface is a filesystem**
+3. **State is inspectable**
+4. **Execution requires approval**
+5. **Discovery replaces configuration**
+
+If a feature violates these axioms, it does not belong in fn.
+
+---
+
+## 3. System Model
+
+### 3.1 The Kernel
+
+The fn kernel is a long-lived Node.js process that:
+
+* maintains sessions,
+* enforces approval,
+* dispatches commands,
+* exposes a virtual filesystem.
+
+The kernel does **not**:
+
+* manage users,
+* enforce permissions,
+* auto-execute AI output,
+* hide state.
+
+---
+
+### 3.2 Sessions
+
+Each connection to fn creates a **session**.
+
+A session has:
+
+* its own namespace,
+* its own `/proc`,
+* its own approval state,
+* isolated command execution.
+
+Sessions are **namespaces**, not users or processes.
+
+---
+
+## 4. Filesystem Layout
+
+Function11 exposes a virtual filesystem rooted at `/`.
+
+```
+/
+├─ bin/        Executable commands
+├─ man/        Command manuals
+└─ proc/       Runtime control and state
+```
+
+Nothing exists outside this structure.
+
+---
+
+## 5. `/bin` — Commands
+
+### 5.1 Command Definition
+
+Each command is a JavaScript ESM module exporting:
+
+```js
+export const meta = {
+  name,
+  description,
+  approval
+};
+
+export async function run(ctx) {}
+```
+
+Commands:
+
+* are discoverable via `ls /bin`
+* document themselves via `man`
+* may request approval
+* may expose streams or filesystems
+
+---
+
+### 5.2 Command Composition
+
+Commands may:
+
+* pipe output to other commands,
+* mount filesystems,
+* expose streams,
+* request privileged execution.
+
+There are **no hidden APIs**.
+
+---
+
+## 6. `/man` — Documentation
+
+Each command has a corresponding manual:
+
+```
+/man/<command>.md
+```
+
+The `man` command renders these files.
+
+Manuals are:
+
+* human-readable,
+* AI-readable,
+* authoritative.
+
+If a command lacks a manual, it is incomplete.
+
+---
+
+## 7. `/proc` — Control Surfaces
+
+`/proc` is the primary control and introspection interface.
+
+It is **bidirectional**.
+
+### 7.1 `/proc/self`
+
+Session-scoped control.
+
+```
+/proc/self/
+├─ status     Session state
+├─ approve    Approval gate
+├─ stdin      Input stream
+├─ stdout     Output stream
+└─ kill       Terminate session
+```
+
+A session always has access to its own `/proc/self`.
+
+---
+
+### 7.2 `/proc/sys`
+
+Global system state.
+
+```
+/proc/sys/
+├─ uptime
+├─ loglevel
+└─ sessions
+```
+
+Writes to `/proc/sys` affect the kernel globally.
+
+---
+
+## 8. Approval System
+
+### 8.1 Purpose
+
+No command may:
+
+* execute host commands,
+* run containers,
+* modify the system,
+
+without **explicit approval**.
+
+Approval is not a prompt.
+It is **state**.
+
+---
+
+### 8.2 `/proc/self/approve`
+
+#### Read
+
+```
+cat /proc/self/approve
+```
+
+Outputs:
+
+* `idle` if no request is pending
+* otherwise, a structured approval request
+
+#### Write
+
+```
+echo yes > /proc/self/approve
+echo no  > /proc/self/approve
+```
+
+Resolves the request.
+
+Approval is:
+
+* session-scoped,
+* blocking,
+* auditable,
+* impossible to bypass.
+
+---
+
+## 9. Human Interaction
+
+### 9.1 Interactive Shell
+
+Humans interact with fn via:
+
+```sh
+./fn --interactive
+```
+
+The shell:
+
+* uses readline,
+* supports pipelines,
+* resolves commands via `/bin`,
+* reads state via `/proc`.
+
+The shell is **not special**.
+It is just a client.
+
+---
+
+## 10. AI Interaction
+
+### 10.1 AI as a Client
+
+AI systems interact with fn exactly as humans do.
+
+They may:
+
+* list commands,
+* read manuals,
+* inspect `/proc`,
+* propose actions.
+
+They may **not**:
+
+* self-approve,
+* bypass `/proc/self/approve`,
+* invent commands.
+
+---
+
+### 10.2 AI Discovery Model
+
+AI learns capabilities by:
+
+```
+ls /bin
+man <command>
+ls /proc
+```
+
+No tool schemas.
+No MCP.
+No prompt engineering.
+
+---
+
+## 11. Security Model
+
+Function11 achieves security by:
+
+* eliminating dependency chains,
+* removing hidden execution paths,
+* enforcing approval structurally,
+* making state visible.
+
+There are:
+
+* no background privileges,
+* no implicit trust,
+* no invisible side effects.
+
+---
+
+## 12. Design Lineage
+
+Function11 draws directly from:
+
+* **UNIX** — composability and text streams
+* **Plan 9** — namespaces and file interfaces
+* **Inferno** — supervised concurrency
+* **Early X** — minimalism and pixel clarity
+
+It intentionally rejects:
+
+* package ecosystems,
+* opaque tooling,
+* global mutable state,
+* cloud-dependent AI systems.
+
+---
+
+## 13. What Function11 Is Not
+
+* Not a package manager
+* Not an AI agent framework
+* Not a container platform
+* Not a desktop environment (yet)
+
+It is the **substrate** those things may rest upon.
+
+---
+
+## 14. Status
+
+Function11 is:
+
+* conceptually complete,
+* incrementally implementable,
+* hostile to supply-chain attacks,
+* legible to both humans and AI.
+
+Everything beyond this manual is **refinement**, not reinvention.
+
+---
+
+## Closing Note
+
+Function11 does not attempt to be clever.
+
+It attempts to be **honest**.
+
+Honest systems are inspectable.
+Inspectable systems are secure.
+Secure systems can trust AI.
+
+That is the point of fn.

package/fn.js

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import readline from "node:readline";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const FS_ROOT = path.join(__dirname, "fs");
+
+/* -------------------------
+ * Namespace
+ * ------------------------- */
+class Namespace {
+  constructor(root = FS_ROOT) {
+    this.root = root;
+    this.cwd = "/";
+  }
+
+  resolve(p) {
+    if (!p.startsWith("/")) p = path.join(this.cwd, p);
+    return path.join(this.root, p);
+  }
+}
+
+/* -------------------------
+ * Kernel
+ * ------------------------- */
+class Kernel {
+  constructor() {
+    this.sessions = new Map();
+    this.nextSessionId = 1;
+  }
+
+  createSession(io = {}) {
+    const id = this.nextSessionId++;
+    const session = {
+      id,
+      created: Date.now(),
+      alive: true,
+      stdin: io.stdin || process.stdin,
+      stdout: io.stdout || process.stdout,
+      namespace: new Namespace(),
+      approval: null
+    };
+    this.sessions.set(id, session);
+    return session;
+  }
+
+  listBin() {
+    return fs.readdirSync(path.join(FS_ROOT, "bin"))
+      .filter(f => f.endsWith(".js"))
+      .map(f => f.replace(/\.js$/, ""));
+  }
+
+  async runCommand(session, name, args = []) {
+    const cmdPath = path.join(FS_ROOT, "bin", `${name}.js`);
+    if (!fs.existsSync(cmdPath)) {
+      session.stdout.write(`fn: command not found: ${name}\n`);
+      return;
+    }
+
+    const cmd = await import(cmdPath);
+    const ctx = {
+      args,
+      session,
+      kernel: this,
+      ns: session.namespace,
+      stdout: session.stdout,
+      stderr: process.stderr,
+      approve: async () => true
+    };
+
+    await cmd.run(ctx);
+  }
+
+  async accessProc(session, pathParts, mode, data) {
+    const [scope, name] = pathParts;
+
+    if (scope === "self") {
+      const modPath = path.join(FS_ROOT, "proc", "self", `${name}.js`);
+      if (!fs.existsSync(modPath)) {
+        session.stdout.write(`fn: /proc/self/${name}: no such entry\n`);
+        return;
+      }
+
+      const mod = await import(modPath);
+      const ctx = { session, kernel: this, stdout: session.stdout };
+
+      if (mode === "read" && mod.read) await mod.read(ctx);
+      if (mode === "write" && mod.write) await mod.write(ctx, data);
+      return;
+    }
+
+    if (scope === "sys") {
+      const modPath = path.join(FS_ROOT, "proc", "sys", `${name}.js`);
+      if (!fs.existsSync(modPath)) {
+        session.stdout.write(`fn: /proc/sys/${name}: no such entry\n`);
+        return;
+      }
+
+      const mod = await import(modPath);
+      const ctx = { kernel: this, stdout: session.stdout };
+
+      if (mode === "read" && mod.read) await mod.read(ctx);
+      if (mode === "write" && mod.write) await mod.write(ctx, data);
+      return;
+    }
+
+    session.stdout.write(`fn: /proc/${scope}: invalid scope\n`);
+  }
+
+  async requestApproval(session, request) {
+    if (session.approval) {
+      throw new Error("approval already pending");
+    }
+
+    let resolve;
+    const promise = new Promise(r => (resolve = r));
+
+    session.approval = {
+      request,
+      resolve
+    };
+
+    return promise;
+  }
+}
+
+/* -------------------------
+ * Interactive Shell
+ * ------------------------- */
+const kernel = new Kernel();
+const session = kernel.createSession({
+  stdin: process.stdin,
+  stdout: process.stdout
+});
+
+const rl = readline.createInterface({
+  input: process.stdin,
+  output: process.stdout,
+  prompt: "fn> "
+});
+
+rl.prompt();
+
+rl.on("line", async line => {
+  line = line.trim();
+
+  // proc write: echo X > /proc/name
+  const writeMatch = line.match(/^echo\s+(.+)\s+>\s+\/proc\/(.+)/);
+  if (writeMatch) {
+    const [, data, p] = writeMatch;
+    await kernel.accessProc(session, p.split("/"), "write", data);
+    rl.prompt();
+    return;
+  }
+
+  // proc read: cat /proc/name
+  const readMatch = line.match(/^cat\s+\/proc\/(.+)/);
+  if (readMatch) {
+    const [, p] = readMatch;
+    await kernel.accessProc(session, p.split("/"), "read");
+    rl.prompt();
+    return;
+  }
+
+  const [cmd, ...args] = line.split(/\s+/);
+  if (cmd) await kernel.runCommand(session, cmd, args);
+  rl.prompt();
+});
+
+rl.on("close", () => {
+  console.log("fn: session ended");
+  process.exit(0);
+});

package/fs/bin/host.exec.js

@@ -0,0 +1,22 @@
+export const meta = {
+  name: "host.exec",
+  description: "Execute host command (requires approval)",
+  approval: "host"
+};
+
+export async function run(ctx) {
+  const cmd = ctx.args.join(" ");
+
+  const ok = await ctx.kernel.requestApproval(ctx.session, {
+    action: "host-exec",
+    command: cmd,
+    reason: "execute host command"
+  });
+
+  if (!ok) {
+    ctx.stdout.write("execution denied\n");
+    return;
+  }
+
+  ctx.stdout.write(`(pretend) running: ${cmd}\n`);
+}

package/fs/bin/ls.js

@@ -0,0 +1,14 @@
+export const meta = {
+  name: "ls",
+  description: "List commands",
+  approval: "none"
+};
+
+export async function run(ctx) {
+  const bin = ctx.ns.resolve("/bin");
+  const files = (await import("node:fs")).default
+    .readdirSync(bin)
+    .filter(f => f.endsWith(".js"))
+    .map(f => f.replace(/\.js$/, ""));
+  ctx.stdout.write(files.join("\n") + "\n");
+}

package/fs/bin/man.js

@@ -0,0 +1,21 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export const meta = {
+  name: "man",
+  description: "Show manual",
+  approval: "none"
+};
+
+export async function run(ctx) {
+  const [cmd] = ctx.args;
+  if (!cmd) return ctx.stdout.write("usage: man <command>\n");
+
+  const manPath = ctx.ns.resolve(`/man/${cmd}.md`);
+  if (!fs.existsSync(manPath)) {
+    ctx.stdout.write(`man: no entry for ${cmd}\n`);
+    return;
+  }
+
+  ctx.stdout.write(fs.readFileSync(manPath, "utf8"));
+}

package/fs/man/ls.md

@@ -0,0 +1,26 @@
+# ls
+
+List all available commands in `/bin`.
+
+## Usage
+
+```
+ls
+```
+
+## Description
+
+Lists all executable commands available in the Function11 environment. Each command is a JavaScript module in `/bin` that exports a `meta` object and a `run` function.
+
+## Examples
+
+```
+fn> ls
+ls
+man
+host.exec
+```
+
+## See Also
+
+- man(1) - read command documentation

package/fs/man/man.md

@@ -0,0 +1,31 @@
+# man
+
+Display command documentation.
+
+## Usage
+
+```
+man <command>
+```
+
+## Description
+
+Reads and displays the manual page for the specified command. Manual pages are stored in `/man` as Markdown files.
+
+This is the primary discovery mechanism for understanding what commands do and how to use them.
+
+## Examples
+
+```
+fn> man ls
+# ls
+List all available commands...
+```
+
+## Discoverable by AI
+
+AI systems can use `man` to learn about available commands without requiring external schemas or tool definitions. The filesystem itself is the API.
+
+## See Also
+
+- ls(1) - list available commands

package/fs/proc/self/approve.js

@@ -0,0 +1,33 @@
+export async function read(ctx) {
+  const a = ctx.session.approval;
+  if (!a) {
+    ctx.stdout.write("idle\n");
+    return;
+  }
+
+  ctx.stdout.write(
+    "PENDING APPROVAL\n" +
+    `action: ${a.request.action}\n` +
+    `command: ${a.request.command}\n` +
+    `reason: ${a.request.reason}\n`
+  );
+}
+
+export async function write(ctx, data) {
+  const a = ctx.session.approval;
+  if (!a) {
+    ctx.stdout.write("no pending approval\n");
+    return;
+  }
+
+  const v = data.trim().toLowerCase();
+  if (v !== "yes" && v !== "no") {
+    ctx.stdout.write("write 'yes' or 'no'\n");
+    return;
+  }
+
+  ctx.session.approval = null;
+  a.resolve(v === "yes");
+
+  ctx.stdout.write(`approval ${v}\n`);
+}

package/fs/proc/self/kill.js

@@ -0,0 +1,5 @@
+export async function write(ctx) {
+  ctx.session.alive = false;
+  ctx.stdout.write("session terminated\n");
+  process.exit(0);
+}

package/fs/proc/self/status.js

@@ -0,0 +1,8 @@
+export async function read(ctx) {
+  const s = ctx.session;
+  ctx.stdout.write(
+    `id: ${s.id}\n` +
+    `alive: ${s.alive}\n` +
+    `uptime: ${Math.floor((Date.now() - s.created)/1000)}s\n`
+  );
+}