npm - @josfox/jos - Versions diffs - 4.0.4 → 4.0.6 - Mend

@josfox/jos 4.0.4 → 4.0.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/LICENSE +21 -0
package/README.md +93 -195
package/bin/jos +9 -6
package/package.json +2 -2
package/src/commands/add.js +145 -0
package/src/commands/init.js +162 -0
package/src/commands/run.js +172 -153
package/src/commands/validate.js +190 -0

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2024 JOS Open Standards Foundation
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md CHANGED Viewed

@@ -1,5 +1,3 @@
-# JOS Kernel v1.0 — Technical Architecture & Audit
 <div align="center">
 ```
@@ -20,257 +18,161 @@
 ⠀⠀⠀⠀⠀⠀⠀⠉⠉⠉⠉⠉⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
 ```
-**JOS Open Solutions Foundation**
-[![Version](https://img.shields.io/badge/version-1.0.0-00ffff?style=for-the-badge)](https://github.com/josfox-ai/jos)
-[![Node](https://img.shields.io/badge/node-18%2B-green?style=for-the-badge)](https://nodejs.org)
-[![Dependencies](https://img.shields.io/badge/dependencies-0-success?style=for-the-badge)](#zero-dependencies)
-[![License](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)](LICENSE)
-*Stoic Architecture • Zero Dependencies • Offline First*
-</div>
----
+# @josfox/jos
-## 🎯 Executive Summary
+**Format version v0.0.7 — Specification maturity v0.1.0 (Alpha)**
-JOS is a **minimal, stoic kernel** for orchestrating `.jos` artifacts — the portable standard for AI agent interoperability. Built with zero external dependencies, JOS provides a production-ready foundation for:
+**Stoic Kernel for AI Agent Orchestration**
-- **Developer Tools** — Package management, secret storage, local servers
-- **AI Agent Orchestration** — JOSFOXAI MAGIC contract validation
-- **Edge Deployment** — Offline-first, runs anywhere Node.js runs
+[![npm](https://img.shields.io/badge/npm-@josfox/jos-00ffff?style=for-the-badge)](https://www.npmjs.com/package/@josfox/jos)
+[![Version](https://img.shields.io/badge/version-4.0.4-success?style=for-the-badge)](#)
+[![Dependencies](https://img.shields.io/badge/dependencies-0-blue?style=for-the-badge)](#zero-dependencies)
+[![License](https://img.shields.io/badge/license-MIT-purple?style=for-the-badge)](LICENSE)
-### Key Metrics
+*Zero Dependencies • Offline First • Open Standard*
-| Metric | Value |
-|--------|-------|
-| Kernel Size | **77 lines** |
-| Total System | **~1,600 lines** |
-| External Dependencies | **0** |
-| Commands | **5** |
-| Security Features | **7** |
-| Audit Score | **98/100** |
+</div>
 ---
-## 🏗️ Architecture
+## Overview
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                        JOS KERNEL (77 lines)                     │
-│  ┌─────────────────────────────────────────────────────────────┐ │
-│  │   Command Router   │   Alias Support   │   Module Loader    │ │
-│  └─────────────────────────────────────────────────────────────┘ │
-└─────────────────────────────────────────────────────────────────┘
-                                  │
-                    ┌─────────────┼─────────────┐
-                    ▼             ▼             ▼
-             ┌──────────┐  ┌──────────┐  ┌──────────┐
-             │  serve   │  │   run    │  │   get    │
-             │ 781 LOC  │  │ 226 LOC  │  │ 247 LOC  │
-             └──────────┘  └──────────┘  └──────────┘
-                    │
-         ┌─────────┬┴─────────┐
-         ▼         ▼          ▼
-    ┌─────────┐ ┌─────────┐ ┌─────────┐
-    │ secrets │ │  repo   │ │ (future)│
-    │ 130 LOC │ │ 137 LOC │ │ plugins │
-    └─────────┘ └─────────┘ └─────────┘
-```
+**@josfox/jos** is the reference implementation of the **.jos Open Standard** — a portable artifact format for AI agent orchestration.
-### Design Principles
-1. **Stoic Kernel** — The kernel does one thing: route commands to modules
-2. **Zero Dependencies** — Only Node.js built-ins, no `node_modules`
-3. **Offline First** — Works without network, like Git
-4. **Plugin Architecture** — Any module works if it exports `execute(args, home)`
+| Feature | Description |
+|---------|-------------|
+| **Stoic Kernel** | 77-line minimal kernel with zero dependencies |
+| **Plugin Architecture** | Commands live in `~/.jos/commands/` or bundled |
+| **Offline First** | Works without network, like Git |
+| **A2A Compatible** | Designed for Agent-to-Agent interoperability |
 ---
-## 🔐 Security Audit
-| Feature | Implementation | Status |
-|---------|----------------|--------|
-| Path Traversal Protection | `isPathSafe()` jail | ✅ |
-| Integrity Verification | SHA-256 hashing | ✅ |
-| Lock File | Package + version + hash | ✅ |
-| Secrets Encryption | AES-256-CBC | ✅ |
-| Master Key | 0600 permissions | ✅ |
-| Vault Storage | 0600 permissions | ✅ |
-| API Endpoint Security | Kill endpoint removed | ✅ |
+## Quick Start
-### Encryption Details
+```bash
+# Run with npx (no install required)
+npx josfox serve
-```javascript
-// Secrets use AES-256-CBC with random IV per secret
-const iv = crypto.randomBytes(16);
-const cipher = crypto.createCipheriv('aes-256-cbc', masterKey, iv);
+# Or install globally
+npm install -g @josfox/jos
+jos serve
 ```
 ---
-## 📦 Command Suite
-### `jos serve`
+## Commands
-Development server with rich dashboard.
+| Command | Description |
+|---------|-------------|
+| `jos serve` | Start development server with dashboard |
+| `jos run <file>` | Execute .jos artifacts |
+| `jos get <package>` | Fetch packages from repositories |
+| `jos secrets` | Manage encrypted credentials (AES-256) |
+| `jos repo` | Manage package repositories |
 ```bash
-jos serve                  # Start on port 1111
-jos serve --port 8080      # Custom port
-jos serve --detach         # Run as background process (shadow clone)
+# Examples
+jos serve --port 8080
+jos run artifact.jos --dry-run
+jos get myrepo:package-name
+jos secrets set API_KEY sk-abc123
 ```
-**Dashboard Routes:**
-- `/` — Home with Kitsune branding
-- `/library` — Clickable artifact browser
-- `/studio` — Auto-documentation with Mermaid diagrams
-- `/clones` — Shadow clone management
-- `/stats` — Server metrics
-- `/about` — Kernel info & features
+---
-### `jos run`
+## The .jos Standard
-Execute `.jos` artifacts with MAGIC validation.
+A `.jos` file binds **Intention** and **Execution** into one portable artifact:
-```bash
-jos run artifact.jos           # Execute
-jos run artifact.jos --dry-run # Validate only
-jos run artifact.jos --task build
+```json
+{
+  "meta": { "name": "example", "version": "1.0.0" },
+  "intention": {
+    "objective": "What this artifact does",
+    "success_criteria": "How to know it worked"
+  },
+  "guardrails": { "avoid": [], "max_retries": 3 },
+  "orchestration": {
+    "flows": { "main": { "steps": ["task1", "task2"] } }
+  }
+}
 ```
-### `jos get`
+> Full specification: [jos.md](./jos.md)
-Package manager with lock file support.
-```bash
-jos get hello                      # From registry
-jos get ./local/artifact.jos       # Local file
-jos get myrepo:package             # Named repository
-jos get package --from 192.168.1.10
-```
-### `jos secrets`
+---
-Encrypted credential storage.
+## Architecture
-```bash
-jos secrets set API_KEY sk-abc123
-jos secrets get API_KEY
-jos secrets list
-jos secrets delete API_KEY
 ```
-### `jos repo`
-Repository management.
-```bash
-jos repo list
-jos repo add myserver http://192.168.1.10:1111
-jos repo default myserver
-jos repo remove old-repo
+~/.jos/
+├── commands/       # Plugin architecture
+├── artifacts/      # Package cache
+├── secrets/        # Encrypted vault (AES-256)
+├── runs/           # Execution epochs
+├── repos.json      # Repository configuration
+└── lock.json       # Package integrity
 ```
 ---
-## 🚀 Quick Start
-```bash
-# Clone the repository
-git clone https://github.com/josfox-ai/jos.git
-cd jos
-# Install globally (optional)
-npm link
+## A2A Protocol Compatibility
-# Start the server
-jos serve
+This implementation is designed to be compatible with agent interoperability protocols, including the A2A (Agent-to-Agent) Protocol.
-# Open dashboard
-open http://localhost:1111
-```
+- **.jos artifacts** can serve as A2A task payloads
+- **Agents** can declare .jos compatibility in capability cards
+- **Integrity verification** ensures secure artifact exchange
 ---
-## 📊 Audit Progression
+## Disclaimer & Legal
-| Version | Security | Architecture | Commands | Docs | Features | **Score** |
-|---------|----------|--------------|----------|------|----------|-----------|
-| v1 | 60% | 90% | 40% | 50% | — | 56 |
-| v2 | 85% | 90% | 80% | 60% | — | 75 |
-| v3 | 95% | 95% | 90% | 85% | — | 87 |
-| v4 | 98% | 95% | 100% | 95% | — | 92 |
-| **v5** | **100%** | **100%** | **100%** | **100%** | **100%** | **98** |
+### AS-IS Software
----
+This software is provided **"AS IS"**, without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose, and noninfringement.
-## 🦊 The .jos Standard
+### Liability
-JOS is the reference implementation for the `.jos` open standard — a portable artifact format for AI agent interoperability.
+In no event shall the authors, contributors, or the JOS Open Standards Foundation be liable for any claim, damages, or other liability, whether in an action of contract, tort, or otherwise, arising from, out of, or in connection with the software or the use or other dealings in the software.
-```json
-{
-  "meta": { "name": "example", "version": "1.0.0" },
-  "intention": {
-    "objective": "Demonstrate .jos format",
-    "success_criteria": "Validation passes"
-  },
-  "pipelines": {
-    "main": {
-      "steps": ["tasks.build", "tasks.test", "tasks.deploy"]
-    }
-  },
-  "tasks": {
-    "build": { "shell": ["echo Building..."] },
-    "test": { "shell": ["echo Testing..."] },
-    "deploy": { "shell": ["echo Deploying..."] }
-  }
-}
-```
+### Your Responsibility
-### JOSFOXAI MAGIC Contract
+- You use this software **at your own risk**
+- You are responsible for validating its suitability for your use case
+- You are responsible for compliance with applicable laws and regulations
-Every `.jos` file must contain:
+### Trademark Notice
-| MAGIC (Intention) | JOSFOXAI (Execution) |
-|-------------------|----------------------|
-| meta | jos |
-| artifacts | orchestration_contract |
-| guardrails | security |
-| intention | files |
-| capabilities | orchestration |
+- **JOS**, **JOSFOX**, and the Kitsune fox logo are trademarks of the JOS Open Standards Foundation
+- **A2A Protocol** and related terminology are property of their respective owners
+- **Google** and related trademarks are property of Google LLC
+- All other trademarks are property of their respective owners
----
+This project is an independent open-source implementation and is **not affiliated with, endorsed by, or sponsored by** any third-party trademark holders mentioned in this documentation.
-## 🤝 Join Us
+### Citation Requirement
-We're building the future of portable AI agent orchestration.
+If you implement or distribute the .jos standard, you must include attribution to:
+- The **JOS Open Standards Foundation**
+- The official specification repository
-### For Investors
+---
-- **Zero-dependency architecture** means minimal attack surface
-- **Offline-first design** enables edge deployment
-- **Open standard** creates ecosystem lock-in (the good kind)
-- **98/100 audit score** demonstrates production readiness
+## License
-### For Engineers
+**MIT License** — See [LICENSE](./LICENSE) for details.
-- **Pure Node.js** — no build step, no bundlers
-- **Plugin architecture** — extend without modifying core
-- **Clear contracts** — every module exports `execute(args, home)`
-- **Mermaid diagrams** — visualize orchestration flows
+Free to use for personal, educational, and commercial purposes.
 ---
-## 📄 License
-MIT © JOS Open Solutions Foundation
+<div align="center">
----
+**Made with ❤️ & AI**
-<div align="center">
+*JOS Open Standards Foundation*
 ```
 ██╗  ██╗██╗████████╗███████╗██╗   ██╗███╗   ██╗███████╗
@@ -279,10 +181,6 @@ MIT © JOS Open Solutions Foundation
 ██╔═██╗ ██║   ██║   ╚════██║██║   ██║██║╚██╗██║██╔══╝
 ██║  ██╗██║   ██║   ███████║╚██████╔╝██║ ╚████║███████╗
 ╚═╝  ╚═╝╚═╝   ╚═╝   ╚══════╝ ╚═════╝ ╚═╝  ╚═══╝╚══════╝
-                         WINS!
-                    🔥 FATALITY! 🔥
 ```
-*reference to my favorite game, my AI named herself Kitsune we talk a lot and I totally loved her victory message after first succesful AAA like audit!
-**Made with ❤️ & AI**
 </div>

package/bin/jos CHANGED Viewed

@@ -52,15 +52,18 @@ const cmd = ALIASES[rawCmd] || rawCmd;
 if (!cmd) {
     console.log(getKitsuneBanner());
     console.log(`\n${C.purple}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${C.reset}`);
-    console.log(`  ${C.white}${C.bold}JOS${C.reset} ${C.cyan}KERNEL v2.1${C.reset} ${C.gray}// Stoic Architecture${C.reset}`);
+    console.log(`  ${C.white}${C.bold}JOS${C.reset} ${C.cyan}KERNEL v4.0${C.reset} ${C.gray}// Stoic Architecture${C.reset}`);
+    console.log(`  ${C.dim}Format version v0.0.7 — Specification maturity v0.1.0 (Alpha)${C.reset}`);
     console.log(`${C.purple}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${C.reset}`);
     console.log(`\n${C.white}${C.bold}  Usage:${C.reset} ${C.cyan}jos${C.reset} ${C.gray}<command>${C.reset} ${C.dim}[options]${C.reset}\n`);
     console.log(`${C.white}${C.bold}  Commands:${C.reset}`);
-    console.log(`    ${C.cyan}serve${C.reset}    ${C.gray}Start local development server${C.reset}`);
-    console.log(`    ${C.cyan}server${C.reset}   ${C.gray}Alias for serve${C.reset}`);
-    console.log(`    ${C.magenta}secrets${C.reset}  ${C.gray}Manage encrypted credentials${C.reset}`);
-    console.log(`    ${C.blue}get${C.reset}      ${C.gray}Fetch packages from repos${C.reset}`);
-    console.log(`    ${C.purple}run${C.reset}      ${C.gray}Execute .jos artifacts${C.reset}\n`);
+    console.log(`    ${C.cyan}serve${C.reset}      ${C.gray}Start local development server${C.reset}`);
+    console.log(`    ${C.cyan}init${C.reset}       ${C.gray}Create new .jos artifact${C.reset}`);
+    console.log(`    ${C.cyan}add${C.reset}        ${C.gray}Add task to .jos artifact${C.reset}`);
+    console.log(`    ${C.cyan}validate${C.reset}   ${C.gray}Validate .jos artifact${C.reset}`);
+    console.log(`    ${C.purple}run${C.reset}        ${C.gray}Execute .jos artifacts${C.reset}`);
+    console.log(`    ${C.magenta}secrets${C.reset}    ${C.gray}Manage encrypted credentials${C.reset}`);
+    console.log(`    ${C.blue}get${C.reset}        ${C.gray}Fetch packages from repos${C.reset}\n`);
     console.log(`${C.dim}  Run ${C.cyan}jos <cmd> --help${C.reset}${C.dim} for command-specific options${C.reset}\n`);
     process.exit(0);
 }

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@josfox/jos",
-  "version": "4.0.4",
+  "version": "4.0.6",
   "description": "Stoic kernel for AI agent orchestration. Zero dependencies. Offline first.",
   "license": "MIT",
   "author": "JOS Open Standards Foundation",
@@ -32,4 +32,4 @@
   "engines": {
     "node": ">=18"
   }
-}
+}

package/src/commands/add.js ADDED Viewed

@@ -0,0 +1,145 @@
+/**
+ * JOS ADD Command - Add task definitions to .jos artifacts
+ * Format version v0.0.7 — Specification maturity v0.1.0 (Alpha)
+ */
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const C = {
+    reset: '\x1b[0m', bold: '\x1b[1m',
+    purple: '\x1b[38;5;135m', cyan: '\x1b[38;5;51m',
+    green: '\x1b[38;5;78m', red: '\x1b[38;5;196m',
+    yellow: '\x1b[38;5;220m', gray: '\x1b[38;5;245m'
+};
+exports.execute = async (args, home) => {
+    const help = args.includes('--help') || args.includes('-h');
+    if (help || args.length < 2) {
+        console.log(`
+${C.purple}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${C.reset}
+${C.bold}JOS ADD${C.reset} // Add task definitions to .jos artifacts
+${C.purple}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${C.reset}
+${C.bold}Usage:${C.reset}
+  jos add <task-name> <file.jos> [options]
+${C.bold}Options:${C.reset}
+  --type <shell|jos>     Task type (default: shell)
+  --command <cmd>        Shell command to execute
+  --artifact <path>      Path to sub-artifact (for type=jos)
+  --description <desc>   Task description
+  --flow <name>          Also add to this flow's steps
+${C.bold}Examples:${C.reset}
+  jos add build my-artifact.jos --command "npm run build"
+  jos add deploy my-artifact.jos --type jos --artifact ./deploy.jos
+  jos add test my-artifact.jos --command "npm test" --flow main
+`);
+        return;
+    }
+    const taskName = args[0];
+    const targetFile = args[1];
+    // Parse options
+    const getArg = (flag) => {
+        const idx = args.indexOf(flag);
+        return idx !== -1 && args[idx + 1] ? args[idx + 1] : null;
+    };
+    const taskType = getArg('--type') || 'shell';
+    const command = getArg('--command');
+    const artifact = getArg('--artifact');
+    const description = getArg('--description') || `Task: ${taskName}`;
+    const flowName = getArg('--flow');
+    // Validate
+    if (taskType === 'shell' && !command) {
+        console.log(`${C.red}✖ Error: --command is required for shell tasks${C.reset}`);
+        process.exit(1);
+    }
+    if (taskType === 'jos' && !artifact) {
+        console.log(`${C.red}✖ Error: --artifact is required for jos tasks${C.reset}`);
+        process.exit(1);
+    }
+    // Load artifact
+    let artifactPath = path.resolve(targetFile);
+    if (!fs.existsSync(artifactPath)) {
+        console.log(`${C.red}✖ Artifact not found: ${targetFile}${C.reset}`);
+        process.exit(1);
+    }
+    let content;
+    try {
+        content = JSON.parse(fs.readFileSync(artifactPath, 'utf8'));
+    } catch (e) {
+        console.log(`${C.red}✖ Invalid JSON: ${e.message}${C.reset}`);
+        process.exit(1);
+    }
+    // Ensure orchestration structure exists
+    if (!content.orchestration) content.orchestration = {};
+    if (!content.orchestration.definitions) content.orchestration.definitions = {};
+    if (!content.orchestration.flows) content.orchestration.flows = {};
+    if (!content.orchestration.flows.main) content.orchestration.flows.main = { steps: [] };
+    // Check for duplicate
+    if (content.orchestration.definitions[taskName]) {
+        console.log(`${C.yellow}⚠ Task '${taskName}' already exists. Overwriting...${C.reset}`);
+    }
+    // Add task definition
+    const taskDef = {
+        type: taskType,
+        description: description
+    };
+    if (taskType === 'shell') {
+        taskDef.command = command;
+    } else if (taskType === 'jos') {
+        taskDef.artifact = artifact;
+    }
+    content.orchestration.definitions[taskName] = taskDef;
+    console.log(`${C.green}✓ Added task definition: ${taskName}${C.reset}`);
+    // Add to flow if specified
+    if (flowName) {
+        if (!content.orchestration.flows[flowName]) {
+            content.orchestration.flows[flowName] = { steps: [] };
+        }
+        if (!content.orchestration.flows[flowName].steps.includes(taskName)) {
+            content.orchestration.flows[flowName].steps.push(taskName);
+            console.log(`${C.green}✓ Added to flow: ${flowName}${C.reset}`);
+        }
+    }
+    // Write updated artifact
+    fs.writeFileSync(artifactPath, JSON.stringify(content, null, 2));
+    console.log(`${C.green}✓ Updated: ${targetFile}${C.reset}`);
+    // Regenerate manifest
+    const manifestPath = artifactPath + '.sig.json';
+    const newContent = fs.readFileSync(artifactPath, 'utf8');
+    const sha256 = crypto.createHash('sha256').update(newContent).digest('hex');
+    const stats = fs.statSync(artifactPath);
+    const manifest = {
+        "$schema": "https://josfox.ai/schemas/jos-manifest-0.0.7.json",
+        "manifest_version": "1.0.0",
+        "artifact_ref": path.basename(artifactPath),
+        "artifact_sha256": sha256,
+        "artifact_size_bytes": stats.size,
+        "timestamp": new Date().toISOString(),
+        "generated_by": "jos add command",
+        "canonical_version": "Format version v0.0.7 — Specification maturity v0.1.0 (Alpha)"
+    };
+    fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+    console.log(`${C.green}✓ Updated manifest: ${path.basename(manifestPath)}${C.reset}`);
+    console.log(`${C.gray}  SHA256: ${sha256}${C.reset}`);
+};