@context-os/core 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Discovers the workspace root by looking for root/soul.md in parent directories.
+ */
+export declare function findWorkspaceRoot(): string;
+export declare const workspaceRoot: string;
+/**
+ * Standard ContextOS "Buckets" for security isolation.
+ */
+export declare const ALLOWED_BUCKETS: string[];
+/**
+ * Validates that a path is within the workspace root and inside an allowed bucket.
+ */
+export declare function validatePath(requestedPath: string): {
+    fullPath: string;
+    relativePath: string;
+};
+/**
+ * Checks if a path is in a read-only bucket for agents.
+ */
+export declare function isReadOnly(filePath: string): boolean;
+/**
+ * Executes an atomic git transaction (Add + Commit).
+ */
+export declare function gitCommit(filePath: string, message: string): Promise<void>;

package/dist/index.js

@@ -0,0 +1,88 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import { spawn } from 'node:child_process';
+/**
+ * Discovers the workspace root by looking for root/soul.md in parent directories.
+ */
+export function findWorkspaceRoot() {
+    let current = process.cwd();
+    const root = path.parse(current).root;
+    while (current !== root) {
+        if (fs.existsSync(path.join(current, "root", "soul.md"))) {
+            return fs.realpathSync(current);
+        }
+        current = path.dirname(current);
+    }
+    return fs.realpathSync(process.cwd()); // Fallback to CWD
+}
+export const workspaceRoot = findWorkspaceRoot();
+/**
+ * Standard ContextOS "Buckets" for security isolation.
+ */
+export const ALLOWED_BUCKETS = [
+    "projects",
+    "knowledge",
+    "schemas",
+    "archive",
+    "log",
+    "orgs",
+    "root"
+];
+/**
+ * Validates that a path is within the workspace root and inside an allowed bucket.
+ */
+export function validatePath(requestedPath) {
+    const resolvedPath = path.resolve(workspaceRoot, requestedPath);
+    let fullPath;
+    try {
+        fullPath = fs.realpathSync(resolvedPath);
+    }
+    catch (e) {
+        fullPath = resolvedPath;
+    }
+    const relativePath = path.relative(workspaceRoot, fullPath);
+    // Security check: must be within the workspace root
+    if (relativePath.startsWith("..") || path.isAbsolute(relativePath)) {
+        throw new Error(`Security violation: Path ${requestedPath} is outside the allowed ContextOS workspace root.`);
+    }
+    // Enterprise check: must be within an allowed bucket
+    const isAllowed = ALLOWED_BUCKETS.some(bucket => {
+        const bucketRoot = path.join(workspaceRoot, bucket);
+        const bucketRelative = path.relative(bucketRoot, fullPath);
+        return !bucketRelative.startsWith("..") && !path.isAbsolute(bucketRelative);
+    });
+    if (!isAllowed) {
+        throw new Error(`Security violation: Path ${requestedPath} is outside the allowed bucket (projects, orgs, knowledge, schemas, etc).`);
+    }
+    return { fullPath, relativePath };
+}
+/**
+ * Checks if a path is in a read-only bucket for agents.
+ */
+export function isReadOnly(filePath) {
+    const { fullPath } = validatePath(filePath);
+    const readOnlyBuckets = ["knowledge", "schemas", "root"];
+    return readOnlyBuckets.some(bucket => {
+        const bucketRoot = path.join(workspaceRoot, bucket);
+        const bucketRelative = path.relative(bucketRoot, fullPath);
+        return !bucketRelative.startsWith("..") && !path.isAbsolute(bucketRelative);
+    });
+}
+/**
+ * Executes an atomic git transaction (Add + Commit).
+ */
+export async function gitCommit(filePath, message) {
+    return new Promise((resolve, reject) => {
+        const add = spawn("git", ["add", filePath], { cwd: workspaceRoot });
+        add.on("close", (code) => {
+            if (code !== 0 && code !== null) {
+                return reject(new Error(`Git add failed with code ${code}`));
+            }
+            const commit = spawn("git", ["commit", "-m", message], { cwd: workspaceRoot });
+            commit.on("close", (code) => {
+                // If code is not 0, it might be "nothing to commit" which is fine for our tools
+                resolve();
+            });
+        });
+    });
+}

package/dist/tests/security.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/security.test.js

@@ -0,0 +1,33 @@
+import assert from "node:assert";
+import { validatePath, findWorkspaceRoot, ALLOWED_BUCKETS, isReadOnly } from "../index.js";
+import path from "node:path";
+describe("Core Security Engine", () => {
+    const workspaceRoot = findWorkspaceRoot();
+    it("should discover the workspace root (contains root/soul.md)", () => {
+        assert.strictEqual(typeof workspaceRoot, "string");
+        assert.notStrictEqual(workspaceRoot, "/");
+    });
+    it("should allow paths within projects directory", () => {
+        const validPath = path.join(workspaceRoot, "projects", "TestProject", "memory.md");
+        assert.doesNotThrow(() => validatePath(validPath));
+    });
+    it("should block directory traversal attacks (..)", () => {
+        const maliciousPath = path.join(workspaceRoot, "projects", "..", "..", "package.json");
+        assert.throws(() => validatePath(maliciousPath), /Security violation/);
+    });
+    it("should block access to root config files (package.json)", () => {
+        const rootConfig = path.join(workspaceRoot, "package.json");
+        assert.throws(() => validatePath(rootConfig), /Security violation/);
+    });
+    it("should report knowledge, schemas, and root as read-only", () => {
+        assert.strictEqual(isReadOnly("knowledge/domains/ai.md"), true);
+        assert.strictEqual(isReadOnly("schemas/project.json"), true);
+        assert.strictEqual(isReadOnly("root/soul.md"), true);
+        assert.strictEqual(isReadOnly("projects/ContextOS/memory.md"), false);
+    });
+    it("should have a fixed list of allowed security buckets", () => {
+        assert.ok(ALLOWED_BUCKETS.includes("projects"));
+        assert.ok(ALLOWED_BUCKETS.includes("knowledge"));
+        assert.ok(ALLOWED_BUCKETS.includes("schemas"));
+    });
+});

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@context-os/core",
+  "version": "1.0.0",
+  "description": "Shared intelligence layer, schemas, and security buckets for ContextOS",
+  "type": "module",
+  "main": "dist/index.js",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "schemas",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "npm run build && mocha dist/tests/**/*.test.js"
+  },
+  "dependencies": {
+    "fs-extra": "^11.2.0"
+  },
+  "devDependencies": {
+    "@types/chai": "^5.2.3",
+    "@types/fs-extra": "^11.0.4",
+    "@types/mocha": "^10.0.10",
+    "@types/node": "^22.13.9",
+    "chai": "^5.2.0",
+    "mocha": "^11.1.0",
+    "typescript": "^5.8.2"
+  }
+}

package/schemas/context.schema.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ContextOS Context Schema",
+  "description": "Schema for project CONTEXT.md files.",
+  "type": "object",
+  "required": ["Overview", "Goals"],
+  "properties": {
+    "Overview": { "type": "string" },
+    "Goals": {
+      "type": "array",
+      "items": { "type": "string" },
+      "minItems": 1
+    },
+    "Stack": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "Metadata": {
+      "type": "object",
+      "properties": {
+        "Tags": { "type": "array", "items": { "type": "string" } }
+      }
+    }
+  }
+}

package/schemas/decision.schema.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ContextOS Decision Schema",
+  "description": "Schema for project decisions.md files.",
+  "type": "object",
+  "properties": {
+    "Decisions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["Id", "Title", "Date", "Status", "Context", "Decision", "Rationale"],
+        "properties": {
+          "Id": { "type": "string", "pattern": "^ADR-\\d{4}$" },
+          "Title": { "type": "string" },
+          "Date": { "type": "string", "format": "date" },
+          "Status": { "type": "string", "enum": ["Proposed", "Accepted", "Superseded", "Deprecated"] },
+          "Context": { "type": "string" },
+          "Decision": { "type": "string" },
+          "Rationale": { "type": "string" }
+        }
+      }
+    }
+  }
+}

package/schemas/memory.schema.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ContextOS Memory Schema",
+  "description": "Schema for project memory.md files.",
+  "type": "object",
+  "required": ["Overview"],
+  "properties": {
+    "Overview": { "type": "string" },
+    "Learnings": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "Patterns": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "Metadata": {
+      "type": "object",
+      "properties": {
+        "Tags": { "type": "array", "items": { "type": "string" } }
+      }
+    }
+  }
+}

package/schemas/soul.schema.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ContextOS Soul Schema",
+  "description": "Schema for project SOUL.md files defining identity and values.",
+  "type": "object",
+  "required": ["Identity", "Core Principles", "Behavioral Rules"],
+  "properties": {
+    "Identity": {
+      "type": "string",
+      "description": "High-level description of the project's purpose."
+    },
+    "Core Principles": {
+      "type": "array",
+      "items": { "type": "string" },
+      "minItems": 1
+    },
+    "Behavioral Rules": {
+      "type": "array",
+      "items": { "type": "string" },
+      "minItems": 1
+    },
+    "Constraints": {
+      "type": "array",
+      "items": { "type": "string" }
+    }
+  }
+}