qwall-work 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 1.0.0
+
+- Initial production npm release.
+- Gemini/Gemma model discovery.
+- Interactive AI chat.
+- Workspace file tools.
+- Nano integration.
+- User API-key configuration.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Codetable Software
+
+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

@@ -0,0 +1,62 @@
+# Qwall Work
+
+AI workspace CLI powered by the Google Gemini API.
+
+## Features
+
+- Gemini and Gemma model discovery
+- User-owned Gemini API key
+- Interactive AI chat
+- File read/write/edit/list tools
+- Optional nano integration
+- Workspace path protection
+- CommonJS Node.js CLI
+- npm global installation
+
+## Requirements
+
+- Node.js >= 18
+- A Google Gemini API key
+- `nano` only if you want the `open_in_nano` tool
+
+## Install
+
+```bash
+npm install -g qwall-work
+```
+
+Run:
+
+```bash
+qwall
+```
+
+Configure:
+
+```bash
+qwall-work config
+```
+
+List available Gemini/Gemma models:
+
+```bash
+qwall-work models
+```
+
+## Workspace
+
+By default, AI file operations are restricted to:
+
+```text
+<current-directory>/.qwall-workspace
+```
+
+You can choose another workspace:
+
+```bash
+QWALL_WORKSPACE=/path/to/project qwall
+```
+
+## License
+
+MIT - Copyright (c) Codetable Software

package/SECURITY.md

@@ -0,0 +1,5 @@
+# Security Policy
+
+Please do not publish API keys, credentials, private project files, or other secrets in issues.
+
+Report security problems privately to the Codetable Software maintainers.

package/bin/qwall-work.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+"use strict";
+
+require("../src/index.js").main().catch((error) => {
+  console.error(`\nQwall Work: ${error.message}`);
+  if (process.env.QWALL_DEBUG) console.error(error.stack);
+  process.exitCode = 1;
+});

package/docs/configuration.md

@@ -0,0 +1,15 @@
+# Configuration
+
+Set the API key with `qwall-work config` or:
+
+```bash
+export GEMINI_API_KEY="your-key"
+```
+
+Optional model:
+
+```bash
+export QWALL_MODEL="gemini-2.5-flash"
+```
+
+Configuration is stored in `~/.qwall-work/config.json` with restrictive file permissions.

package/docs/models.md

@@ -0,0 +1,17 @@
+# Models
+
+Qwall Work queries the Google Gemini API model list and filters it to Gemini and Gemma models that expose content generation.
+
+Use:
+
+```bash
+qwall-work models
+```
+
+Then select a model with:
+
+```text
+/model
+```
+
+Availability depends on the user's API key and Google's current API catalog.

package/docs/security.md

@@ -0,0 +1,7 @@
+# Security
+
+The AI file tools are restricted to the Qwall Work workspace. Parent-directory traversal such as `../secret` is rejected.
+
+Never commit or publish an API key. Use `GEMINI_API_KEY` or the local Qwall Work configuration.
+
+The model can request file tools, so review generated changes when working on important projects.

package/docs/tools.md

@@ -0,0 +1,13 @@
+# Tools
+
+Qwall Work exposes these AI tools:
+
+- `read_file`
+- `write_file`
+- `edit_file`
+- `list_files`
+- `open_in_nano`
+
+All file paths are constrained to the configured Qwall Work workspace.
+
+`open_in_nano` requires the `nano` executable to be installed and available on PATH.

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "qwall-work",
+  "version": "1.0.0",
+  "description": "AI workspace CLI powered by Google Gemini API",
+  "main": "src/index.js",
+  "type": "commonjs",
+  "bin": {
+    "qwall-work": "./bin/qwall-work.js",
+    "qwall": "./bin/qwall-work.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "docs",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "SECURITY.md"
+  ],
+  "scripts": {
+    "test": "node test/workspace/security.test.js && node test/tools/write-file.test.js && node test/tools/edit-file.test.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@google/genai": "^1.20.0"
+  },
+  "keywords": [
+    "qwall",
+    "qwall-work",
+    "ai",
+    "cli",
+    "gemini",
+    "gemma",
+    "google"
+  ],
+  "author": "Codetable Software",
+  "license": "MIT"
+}

package/src/ai/chat.js

@@ -0,0 +1,56 @@
+const { getClient } = require("./client");
+const { buildTools } = require("./tools");
+const { executeTool } = require("./tool-handler");
+const { getWorkspace } = require("../workspace");
+
+async function ask({ model, input, history, onTool }) {
+  const ai = getClient();
+  const contents = [...history, { role: "user", parts: [{ text: input }] }];
+
+  const response = await ai.models.generateContent({
+    model,
+    contents,
+    config: {
+      tools: buildTools()
+    }
+  });
+
+  const candidate = response.candidates?.[0];
+  const parts = candidate?.content?.parts || [];
+  const toolResults = [];
+
+  for (const part of parts) {
+    if (part.functionCall) {
+      const call = part.functionCall;
+      onTool?.({ name: call.name, status: "running" });
+      const result = await executeTool(call.name, call.args || {}, getWorkspace());
+      toolResults.push({ name: call.name, result });
+      onTool?.({ name: call.name, path: call.args?.path, status: "completed" });
+    }
+  }
+
+  let text = parts.filter(p => p.text).map(p => p.text).join("");
+  let nextHistory = [...contents];
+
+  if (toolResults.length) {
+    const functionResponses = toolResults.map(({ name, result }) => ({
+      functionResponse: { name, response: result }
+    }));
+    nextHistory.push({ role: "model", parts: parts.filter(p => p.functionCall) });
+    nextHistory.push({ role: "user", parts: functionResponses });
+
+    const followup = await ai.models.generateContent({
+      model,
+      contents: nextHistory,
+      config: { tools: buildTools() }
+    });
+    text = followup.text || text;
+    nextHistory.push(followup.candidates?.[0]?.content || { role: "model", parts: [{ text }] });
+  } else {
+    nextHistory.push(candidate?.content || { role: "model", parts: [{ text }] });
+  }
+
+  return { text, history: nextHistory };
+}
+
+module.exports = { ask };

package/src/ai/client.js

@@ -0,0 +1,12 @@
+const { GoogleGenAI } = require("@google/genai");
+const config = require("../config");
+
+function getClient() {
+  const apiKey = config.getApiKey();
+  if (!apiKey) {
+    throw new Error("Gemini API key is not configured. Run `qwall-work config` or set GEMINI_API_KEY.");
+  }
+  return new GoogleGenAI({ apiKey });
+}
+
+module.exports = { getClient };

package/src/ai/models.js

@@ -0,0 +1,23 @@
+const { getClient } = require("./client");
+
+async function fetchModels() {
+  const ai = getClient();
+  const result = [];
+  for await (const model of await ai.models.list()) {
+    const name = model.name || "";
+    const methods = model.supportedActions || model.supportedGenerationMethods || [];
+    const supported = methods.length === 0 || methods.some(m =>
+      String(m).toLowerCase().includes("generatecontent")
+    );
+    if (supported && (/gemini|gemma/i.test(name) || /gemini|gemma/i.test(model.displayName || ""))) {
+      result.push({
+        name,
+        displayName: model.displayName || name,
+        description: model.description || ""
+      });
+    }
+  }
+  return result;
+}
+
+module.exports = { fetchModels };

package/src/ai/streaming.js

@@ -0,0 +1,15 @@
+const { getClient } = require("./client");
+
+async function streamText({ model, contents, onText }) {
+  const ai = getClient();
+  const stream = await ai.models.generateContentStream({ model, contents });
+  let full = "";
+  for await (const chunk of stream) {
+    const text = chunk.text || "";
+    full += text;
+    onText?.(text);
+  }
+  return full;
+}
+
+module.exports = { streamText };

package/src/ai/tool-handler.js

@@ -0,0 +1,13 @@
+const tools = require("../tools");
+
+async function executeTool(name, args, workspace) {
+  switch (name) {
+    case "read_file": return { content: await tools.readFile(args.path, workspace) };
+    case "write_file": return await tools.writeFile(args.path, args.content, workspace);
+    case "edit_file": return await tools.editFile(args.path, args.oldText, args.newText, workspace);
+    case "list_files": return { files: await tools.listFiles(args.path || ".", workspace) };
+    case "open_in_nano": return await tools.openNano(args.path, workspace);
+    default: throw new Error(`Unknown tool: ${name}`);
+  }
+}
+module.exports = { executeTool };

package/src/ai/tools.js

@@ -0,0 +1,59 @@
+function buildTools() {
+  return [{
+    functionDeclarations: [
+      {
+        name: "read_file",
+        description: "Read a UTF-8 text file inside the Qwall Work workspace.",
+        parameters: {
+          type: "OBJECT",
+          properties: { path: { type: "STRING", description: "Relative file path." } },
+          required: ["path"]
+        }
+      },
+      {
+        name: "write_file",
+        description: "Create or replace a UTF-8 text file inside the Qwall Work workspace.",
+        parameters: {
+          type: "OBJECT",
+          properties: {
+            path: { type: "STRING", description: "Relative file path." },
+            content: { type: "STRING", description: "Complete file content." }
+          },
+          required: ["path", "content"]
+        }
+      },
+      {
+        name: "edit_file",
+        description: "Replace an exact text fragment in a UTF-8 file inside the workspace.",
+        parameters: {
+          type: "OBJECT",
+          properties: {
+            path: { type: "STRING" },
+            oldText: { type: "STRING" },
+            newText: { type: "STRING" }
+          },
+          required: ["path", "oldText", "newText"]
+        }
+      },
+      {
+        name: "list_files",
+        description: "List files and directories inside the workspace.",
+        parameters: {
+          type: "OBJECT",
+          properties: { path: { type: "STRING", description: "Relative directory path." } }
+        }
+      },
+      {
+        name: "open_in_nano",
+        description: "Open a workspace file in the nano editor. Use when the user explicitly asks to edit with nano.",
+        parameters: {
+          type: "OBJECT",
+          properties: { path: { type: "STRING" } },
+          required: ["path"]
+        }
+      }
+    ]
+  }];
+}
+
+module.exports = { buildTools };

package/src/cli/commands.js

@@ -0,0 +1,41 @@
+const { startRepl } = require("./repl");
+const { showHelp } = require("./help");
+const { getVersion } = require("../constants/version");
+const config = require("../config");
+const { fetchModels } = require("../ai/models");
+
+async function runCLI(args) {
+  const command = args[0];
+
+  if (args.includes("--help") || command === "help") {
+    showHelp();
+    return;
+  }
+
+  if (args.includes("--version") || command === "version") {
+    console.log(`Qwall Work ${getVersion()}`);
+    return;
+  }
+
+  if (command === "config") {
+    await config.interactive();
+    return;
+  }
+
+  if (command === "models") {
+    const models = await fetchModels();
+    for (const model of models) {
+      console.log(`${model.displayName}  (${model.name})`);
+    }
+    return;
+  }
+
+  await startRepl({ initialModel: getOption(args, "--model") });
+}
+
+function getOption(args, flag) {
+  const index = args.indexOf(flag);
+  return index >= 0 ? args[index + 1] : undefined;
+}
+
+module.exports = { runCLI };

package/src/cli/help.js

@@ -0,0 +1,25 @@
+function showHelp() {
+  console.log(`
+Qwall Work - AI workspace CLI
+
+Usage:
+  qwall-work
+  qwall-work config
+  qwall-work models
+  qwall-work --model <model>
+  qwall-work --help
+  qwall-work --version
+
+Inside chat:
+  /model   Select a Gemini/Gemma model
+  /clear   Clear conversation history
+  /help    Show commands
+  /exit    Exit
+
+Environment:
+  GEMINI_API_KEY   Google Gemini API key
+  QWALL_WORKSPACE  Optional workspace path
+  QWALL_MODEL      Optional default model
+`);
+}
+module.exports = { showHelp };

package/src/cli/prompts.js

@@ -0,0 +1,26 @@
+const readline = require("readline");
+const { fetchModels } = require("../ai/models");
+const config = require("../config");
+
+function question(prompt) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise(resolve => rl.question(prompt, answer => {
+    rl.close();
+    resolve(answer.trim());
+  }));
+}
+
+async function selectModel() {
+  const models = await fetchModels();
+  if (!models.length) throw new Error("No Gemini/Gemma models are available for this API key.");
+
+  console.log("\nAvailable models:");
+  models.forEach((m, i) => console.log(`${i + 1}. ${m.displayName} (${m.name})`));
+
+  const answer = await question(`Select model [1-${models.length}] (current: ${config.getModel() || "none"}): `);
+  const index = Number(answer) - 1;
+  if (!Number.isInteger(index) || !models[index]) throw new Error("Invalid model selection.");
+  return models[index].name;
+}
+
+module.exports = { selectModel };

package/src/cli/renderer.js

@@ -0,0 +1,11 @@
+function renderText(text) {
+  if (text) process.stdout.write(`\nQwall > ${text}\n`);
+}
+
+function renderTool(tool) {
+  console.log(`\n● Tool: ${tool.name}`);
+  if (tool.path) console.log(`  File: ${tool.path}`);
+  if (tool.status) console.log(`  ${tool.status}`);
+}
+
+module.exports = { renderText, renderTool };

package/src/cli/repl.js

@@ -0,0 +1,72 @@
+const readline = require("readline");
+const { ask } = require("../ai/chat");
+const { renderText, renderTool } = require("./renderer");
+const { selectModel } = require("./prompts");
+const config = require("../config");
+const { getWorkspace } = require("../workspace");
+
+async function startRepl({ initialModel } = {}) {
+  let model = initialModel || config.getModel();
+  const workspace = getWorkspace();
+
+  console.log("╭────────────────────────────────────────╮");
+  console.log("│             Qwall Work                 │");
+  console.log("│        Gemini & Gemma AI CLI            │");
+  console.log("╰────────────────────────────────────────╯");
+  console.log(`Model: ${model}`);
+  console.log(`Workspace: ${workspace}`);
+  console.log("Commands: /model  /clear  /help  /exit");
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    prompt: "\nYou > "
+  });
+
+  let history = [];
+  rl.prompt();
+
+  for await (const line of rl) {
+    const input = line.trim();
+    if (!input) { rl.prompt(); continue; }
+
+    if (input === "/exit" || input === "/quit") break;
+    if (input === "/help") {
+      console.log("/model  Select a Gemini/Gemma model");
+      console.log("/clear  Clear conversation history");
+      console.log("/exit   Exit Qwall Work");
+      rl.prompt();
+      continue;
+    }
+    if (input === "/clear") {
+      history = [];
+      console.log("Conversation cleared.");
+      rl.prompt();
+      continue;
+    }
+    if (input === "/model") {
+      model = await selectModel();
+      config.setModel(model);
+      console.log(`Model: ${model}`);
+      rl.prompt();
+      continue;
+    }
+
+    try {
+      const result = await ask({
+        model,
+        input,
+        history,
+        onTool: renderTool
+      });
+      renderText(result.text);
+      history = result.history;
+    } catch (error) {
+      console.error(`\nError: ${error.message}`);
+    }
+    rl.prompt();
+  }
+
+  rl.close();
+}
+module.exports = { startRepl };

package/src/config/api-key.js

@@ -0,0 +1,2 @@
+const config = require("./index");
+module.exports = { getApiKey: config.getApiKey, setApiKey: config.setApiKey };

package/src/config/index.js

@@ -0,0 +1,40 @@
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+
+const DIR = path.join(os.homedir(), ".qwall-work");
+const FILE = path.join(DIR, "config.json");
+
+function load() {
+  try { return JSON.parse(fs.readFileSync(FILE, "utf8")); }
+  catch { return {}; }
+}
+function save(data) {
+  fs.mkdirSync(DIR, { recursive: true, mode: 0o700 });
+  fs.writeFileSync(FILE, JSON.stringify(data, null, 2) + "\n", { mode: 0o600 });
+}
+function getApiKey() {
+  return process.env.GEMINI_API_KEY || load().apiKey || "";
+}
+function setApiKey(apiKey) {
+  const data = load(); data.apiKey = apiKey; save(data);
+}
+function getModel() {
+  return process.env.QWALL_MODEL || load().model || "gemini-2.5-flash";
+}
+function setModel(model) {
+  const data = load(); data.model = model; save(data);
+}
+async function interactive() {
+  const readline = require("readline");
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const ask = p => new Promise(resolve => rl.question(p, resolve));
+  const current = getApiKey();
+  const key = await ask(`Gemini API key ${current ? "(configured, press Enter to keep)" : ""}: `);
+  if (key.trim()) setApiKey(key.trim());
+  const model = await ask(`Model [${getModel()}]: `);
+  if (model.trim()) setModel(model.trim());
+  rl.close();
+  console.log("Configuration saved.");
+}
+module.exports = { getApiKey, setApiKey, getModel, setModel, interactive };

package/src/config/model.js

@@ -0,0 +1,2 @@
+const config = require("./index");
+module.exports = { getModel: config.getModel, setModel: config.setModel };

package/src/config/paths.js

@@ -0,0 +1,5 @@
+const os = require("os");
+const path = require("path");
+function configDir() { return path.join(os.homedir(), ".qwall-work"); }
+function configFile() { return path.join(configDir(), "config.json"); }
+module.exports = { configDir, configFile };

package/src/constants/commands.js

@@ -0,0 +1,6 @@
+module.exports = Object.freeze({
+  HELP: "help",
+  CONFIG: "config",
+  MODELS: "models",
+  VERSION: "version"
+});

package/src/constants/version.js

@@ -0,0 +1,3 @@
+const VERSION = "1.0.0";
+function getVersion() { return VERSION; }
+module.exports = { VERSION, getVersion };

package/src/index.js

@@ -0,0 +1,7 @@
+const { runCLI } = require("./cli/commands");
+
+async function main() {
+  await runCLI(process.argv.slice(2));
+}
+
+module.exports = { main };

package/src/providers/google/client.js

@@ -0,0 +1,9 @@
+const { GoogleGenAI } = require("@google/genai");
+const config = require("../../config");
+
+function createGoogleClient() {
+  const key = config.getApiKey();
+  if (!key) throw new Error("GEMINI_API_KEY is not configured.");
+  return new GoogleGenAI({ apiKey: key });
+}
+module.exports = { createGoogleClient };

package/src/providers/google/errors.js

@@ -0,0 +1,11 @@
+function normalizeGoogleError(error) {
+  const message = error?.message || String(error);
+  if (/api.?key|unauthorized|permission/i.test(message)) {
+    return new Error("Google API authentication failed. Check your Gemini API key.");
+  }
+  if (/quota|rate.?limit|resource.?exhausted/i.test(message)) {
+    return new Error("Google Gemini API quota or rate limit was reached.");
+  }
+  return new Error(message);
+}
+module.exports = { normalizeGoogleError };

package/src/providers/google/models.js

@@ -0,0 +1,2 @@
+const { fetchModels } = require("../../ai/models");
+module.exports = { fetchModels };

package/src/session/context.js

@@ -0,0 +1,8 @@
+function createContext({ workspace, model }) {
+  return {
+    workspace,
+    model,
+    createdAt: new Date().toISOString()
+  };
+}
+module.exports = { createContext };

package/src/session/history.js

@@ -0,0 +1,12 @@
+function createSession() {
+  return { messages: [] };
+}
+function addMessage(session, message) {
+  session.messages.push(message);
+  return session;
+}
+function clearSession(session) {
+  session.messages.length = 0;
+  return session;
+}
+module.exports = { createSession, addMessage, clearSession };

package/src/session/index.js

@@ -0,0 +1,2 @@
+const { createSession, addMessage, clearSession } = require("./history");
+module.exports = { createSession, addMessage, clearSession };

package/src/tools/edit-file.js

@@ -0,0 +1,14 @@
+const fs = require("fs/promises");
+const { resolveSafePath } = require("../workspace/security");
+
+async function editFile(relativePath, oldText, newText, workspace) {
+  const target = resolveSafePath(workspace, relativePath);
+  const content = await fs.readFile(target, "utf8");
+  if (!content.includes(oldText)) {
+    throw new Error(`Text to replace was not found in ${relativePath}.`);
+  }
+  const updated = content.replace(oldText, newText);
+  await fs.writeFile(target, updated, "utf8");
+  return { ok: true, path: relativePath };
+}
+module.exports = { editFile };

package/src/tools/index.js

@@ -0,0 +1,7 @@
+const { readFile } = require("./read-file");
+const { writeFile } = require("./write-file");
+const { editFile } = require("./edit-file");
+const { listFiles } = require("./list-files");
+const { openNano } = require("./nano");
+
+module.exports = { readFile, writeFile, editFile, listFiles, openNano };

package/src/tools/list-files.js

@@ -0,0 +1,12 @@
+const fs = require("fs/promises");
+const { resolveSafePath } = require("../workspace/security");
+
+async function listFiles(relativePath, workspace) {
+  const target = resolveSafePath(workspace, relativePath);
+  const entries = await fs.readdir(target, { withFileTypes: true });
+  return entries.map(entry => ({
+    name: entry.name,
+    type: entry.isDirectory() ? "directory" : "file"
+  }));
+}
+module.exports = { listFiles };

package/src/tools/nano.js

@@ -0,0 +1,16 @@
+const { spawn } = require("child_process");
+const { resolveSafePath } = require("../workspace/security");
+
+function openNano(relativePath, workspace) {
+  const target = resolveSafePath(workspace, relativePath);
+  return new Promise((resolve, reject) => {
+    const child = spawn("nano", [target], { stdio: "inherit" });
+    child.on("error", error => reject(new Error(`Could not start nano: ${error.message}`)));
+    child.on("exit", code => {
+      if (code === 0) resolve({ ok: true, path: relativePath });
+      else reject(new Error(`nano exited with code ${code}.`));
+    });
+  });
+}
+
+module.exports = { openNano };

package/src/tools/read-file.js

@@ -0,0 +1,8 @@
+const fs = require("fs/promises");
+const { resolveSafePath } = require("../workspace/security");
+
+async function readFile(relativePath, workspace) {
+  const target = resolveSafePath(workspace, relativePath);
+  return fs.readFile(target, "utf8");
+}
+module.exports = { readFile };

package/src/tools/write-file.js

@@ -0,0 +1,11 @@
+const fs = require("fs/promises");
+const path = require("path");
+const { resolveSafePath } = require("../workspace/security");
+
+async function writeFile(relativePath, content, workspace) {
+  const target = resolveSafePath(workspace, relativePath);
+  await fs.mkdir(path.dirname(target), { recursive: true });
+  await fs.writeFile(target, String(content), "utf8");
+  return { ok: true, path: relativePath, bytes: Buffer.byteLength(String(content), "utf8") };
+}
+module.exports = { writeFile };

package/src/utils/errors.js

@@ -0,0 +1,8 @@
+class QwallError extends Error {
+  constructor(message, code = "QWALL_ERROR") {
+    super(message);
+    this.name = "QwallError";
+    this.code = code;
+  }
+}
+module.exports = { QwallError };

package/src/utils/logger.js

@@ -0,0 +1,4 @@
+function info(message) { console.log(`[Qwall] ${message}`); }
+function warn(message) { console.warn(`[Qwall] ${message}`); }
+function error(message) { console.error(`[Qwall] ${message}`); }
+module.exports = { info, warn, error };

package/src/utils/paths.js

@@ -0,0 +1,3 @@
+const path = require("path");
+function normalizePath(value) { return path.normalize(value); }
+module.exports = { normalizePath };

package/src/utils/platform.js

@@ -0,0 +1,7 @@
+const os = require("os");
+function platform() { return process.platform; }
+function isWindows() { return process.platform === "win32"; }
+function isLinux() { return process.platform === "linux"; }
+function isMacOS() { return process.platform === "darwin"; }
+function homeDir() { return os.homedir(); }
+module.exports = { platform, isWindows, isLinux, isMacOS, homeDir };

package/src/workspace/index.js

@@ -0,0 +1,9 @@
+const path = require("path");
+const os = require("os");
+const fs = require("fs");
+function getWorkspace() {
+  const workspace = process.env.QWALL_WORKSPACE || path.join(process.cwd(), ".qwall-workspace");
+  fs.mkdirSync(workspace, { recursive: true });
+  return path.resolve(workspace);
+}
+module.exports = { getWorkspace };

package/src/workspace/manager.js

@@ -0,0 +1,9 @@
+const fs = require("fs/promises");
+const { getWorkspace } = require("./index");
+
+async function ensureWorkspace() {
+  const workspace = getWorkspace();
+  await fs.mkdir(workspace, { recursive: true });
+  return workspace;
+}
+module.exports = { ensureWorkspace };

package/src/workspace/security.js

@@ -0,0 +1,16 @@
+const path = require("path");
+
+function resolveSafePath(workspace, relativePath) {
+  if (typeof relativePath !== "string" || !relativePath.trim()) {
+    throw new Error("A file path is required.");
+  }
+  const root = path.resolve(workspace);
+  const target = path.resolve(root, relativePath);
+  const relative = path.relative(root, target);
+  if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    throw new Error("Path escapes the Qwall Work workspace.");
+  }
+  return target;
+}
+
+module.exports = { resolveSafePath };