@sdkurjnk/blackshell 0.2.1 → 0.4.0

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.
package/README.md CHANGED
@@ -49,7 +49,7 @@ Units are **source files**. git-style staging — stage units, then seal the set
49
49
 
50
50
  ```sh
51
51
  blackshell check <source> # preview: is this region eligible? (gate only)
52
- blackshell add <source> --level L1,L3 # stage a unit (default level: L3)
52
+ blackshell add <source> --level 2 # stage a unit (N=1..3, cumulative L1..LN; default 3)
53
53
  blackshell list # show staged units and levels
54
54
  blackshell drop <source> # unstage
55
55
  blackshell enshell # seal all staged units -> object files
@@ -58,7 +58,7 @@ blackshell enshell # seal all staged units -> object files
58
58
  Example:
59
59
 
60
60
  ```sh
61
- blackshell add src/engine/examples/add2.c --level L1,L3
61
+ blackshell add src/engine/examples/add2.c --level 2
62
62
  blackshell enshell
63
63
  ```
64
64
 
package/dist/cli.js CHANGED
@@ -6,12 +6,14 @@
6
6
  import { spawnSync } from "node:child_process";
7
7
  import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
8
8
  import { fileURLToPath } from "node:url";
9
+ import { createRequire } from "node:module";
10
+ import { dirname, join } from "node:path";
9
11
  const here = (p) => fileURLToPath(new URL(p, import.meta.url));
10
12
  const pkg = JSON.parse(readFileSync(here("../package.json"), "utf8"));
11
13
  const USAGE = `blackshell <command> [options]
12
14
 
13
15
  check <source> Gate verdict only (dummy: accept-all)
14
- add <source> [--level L] Stage a unit for sealing (L = e.g. L1,L2; default L3)
16
+ add <source> [--level N] Stage a unit for sealing (N = strength 1..3, cumulative L1..LN; default 3)
15
17
  drop <source> Unstage a unit
16
18
  list Show staged units and their levels
17
19
  enshell Seal every staged unit -> object files
@@ -29,18 +31,38 @@ export function writeStage(units) {
29
31
  mkdirSync(".blackshell", { recursive: true });
30
32
  writeFileSync(STAGE_FILE, JSON.stringify(units, null, 2) + "\n");
31
33
  }
34
+ const MAX_LEVEL = 3; // L1..L3 are the noising dials defined in the plan §6.
35
+ // User-facing dial "N" -> the cumulative set {L1..LN} the engine consumes.
36
+ // The levels stay an orthogonal set in the engine/harness (§9 per-pass toggle);
37
+ // this ladder is only the simple front-door UX. undefined -> full strength.
38
+ // Returns null on an invalid dial so the caller can reject at the boundary.
39
+ export function expandLevel(value) {
40
+ const n = value === undefined ? MAX_LEVEL : Number(value);
41
+ if (!Number.isInteger(n) || n < 1 || n > MAX_LEVEL) {
42
+ return null;
43
+ }
44
+ return Array.from({ length: n }, (_, i) => `L${i + 1}`);
45
+ }
32
46
  export function showLevels(levels) {
33
47
  if (levels.length === 0) {
34
48
  return "L0 (identity)";
35
49
  }
36
50
  return levels.join(",");
37
51
  }
38
- // Resolve the engine binary: the published package ships a per-platform prebuilt
39
- // under vendor/<platform>-<arch>/; a local dev build lands in build/.
52
+ // Resolve the engine binary. The published package pulls the matching engine as an
53
+ // optional dependency @sdkurjnk/blackshell-<platform>-<arch> (os/cpu-gated, so npm
54
+ // installs only the host's); resolve its binary. A local dev build in build/ is the
55
+ // fallback when no platform package is installed.
40
56
  function enginePath() {
41
57
  const exe = process.platform === "win32" ? "blackshell-engine.exe" : "blackshell-engine";
42
- const vendored = here(`../vendor/${process.platform}-${process.arch}/${exe}`);
43
- return existsSync(vendored) ? vendored : here(`../build/${exe}`);
58
+ const pkg = `@sdkurjnk/blackshell-${process.platform}-${process.arch}`;
59
+ try {
60
+ const require = createRequire(import.meta.url);
61
+ return join(dirname(require.resolve(`${pkg}/package.json`)), exe);
62
+ }
63
+ catch {
64
+ return here(`../build/${exe}`);
65
+ }
44
66
  }
45
67
  // --- engine (C++) per-unit primitive call; returns the structured token line ---
46
68
  function engine(args) {
@@ -113,6 +135,14 @@ export function onePositional(rest) {
113
135
  }
114
136
  return positionals[0];
115
137
  }
138
+ // engine argv for sealing one unit; forwards the staged levels (empty = L0).
139
+ export function enshellArgs(u) {
140
+ const args = ["enshell", u.path];
141
+ if (u.levels.length > 0) {
142
+ args.push("--level", u.levels.join(","));
143
+ }
144
+ return args;
145
+ }
116
146
  // --- commands ---
117
147
  function cmdCheck(rest) {
118
148
  const src = onePositional(rest);
@@ -135,7 +165,11 @@ function cmdAdd(rest) {
135
165
  console.error(`error: file not found: ${src}`);
136
166
  return 1;
137
167
  }
138
- const levels = opt.value ? opt.value.split(",").map((s) => s.trim()).filter(Boolean) : ["L3"];
168
+ const levels = expandLevel(opt.value);
169
+ if (levels === null) {
170
+ console.error(`error: --level must be an integer 1..${MAX_LEVEL}`);
171
+ return 1;
172
+ }
139
173
  const units = readStage().filter((u) => u.path !== src);
140
174
  units.push({ path: src, levels });
141
175
  writeStage(units);
@@ -177,7 +211,7 @@ function cmdEnshell() {
177
211
  }
178
212
  let code = 0;
179
213
  for (const u of units) {
180
- const { token, status } = engine(["enshell", u.path]);
214
+ const { token, status } = engine(enshellArgs(u));
181
215
  emit(token);
182
216
  if (status !== 0) {
183
217
  code = status;
package/package.json CHANGED
@@ -1,22 +1,20 @@
1
1
  {
2
2
  "name": "@sdkurjnk/blackshell",
3
- "version": "0.2.1",
3
+ "version": "0.4.0",
4
4
  "description": "Build-stage protection tool that seals critical code regions at the compiler IR level, communicating with the outside only by value.",
5
5
  "type": "module",
6
6
  "bin": {
7
7
  "blackshell": "dist/cli.js"
8
8
  },
9
9
  "files": [
10
- "dist/",
11
- "src/",
12
- "vendor/"
10
+ "dist/"
13
11
  ],
14
12
  "scripts": {
15
- "build:engine": "node -e \"require('fs').mkdirSync('build',{recursive:true})\" && g++ -std=c++17 -O2 -o build/blackshell-engine src/engine/main.cpp src/engine/driver.cpp src/engine/frontend.cpp src/engine/gate.cpp src/engine/noising.cpp src/engine/harness.cpp src/engine/backend.cpp",
16
- "build:engine-test": "node -e \"require('fs').mkdirSync('build',{recursive:true})\" && g++ -std=c++17 -O2 -I src/engine -o build/blackshell-engine-test test/engine/engine_test.cpp src/engine/driver.cpp src/engine/frontend.cpp src/engine/gate.cpp src/engine/noising.cpp src/engine/harness.cpp src/engine/backend.cpp",
13
+ "build:engine": "node scripts/build-engine.mjs",
14
+ "build:engine-test": "node scripts/build-engine.mjs --test",
17
15
  "build:ts": "tsc",
18
16
  "build": "npm run build:engine && npm run build:ts",
19
- "pretest": "npm run build && npm run build:engine-test",
17
+ "pretest": "npm run build:engine-test && npm run build:ts",
20
18
  "test": "node --test"
21
19
  },
22
20
  "engines": {
@@ -45,5 +43,12 @@
45
43
  "devDependencies": {
46
44
  "@types/node": "^26.6.6",
47
45
  "typescript": "^7.0.2"
46
+ },
47
+ "optionalDependencies": {
48
+ "@sdkurjnk/blackshell-darwin-arm64": "0.4.0",
49
+ "@sdkurjnk/blackshell-darwin-x64": "0.4.0",
50
+ "@sdkurjnk/blackshell-linux-arm64": "0.4.0",
51
+ "@sdkurjnk/blackshell-linux-x64": "0.4.0",
52
+ "@sdkurjnk/blackshell-win32-x64": "0.4.0"
48
53
  }
49
54
  }
@@ -1,9 +0,0 @@
1
- #include "engine.hpp"
2
- #include <cstdlib>
3
-
4
- // Backend (LLVM / llc): compile LLVM IR to an object file. BLACK BOX — real LLVM.
5
- // shortcut: std::system with naive quoting; upgrade to argv exec if needed.
6
- bool backend_emit(const std::string& ir, const std::string& obj_out) {
7
- const std::string cmd = "llc -filetype=obj \"" + ir + "\" -o \"" + obj_out + "\"";
8
- return std::system(cmd.c_str()) == 0;
9
- }
@@ -1,33 +0,0 @@
1
- #include "engine.hpp"
2
- #include <cstdio>
3
- #include <string>
4
-
5
- static std::string stem(const std::string& path) {
6
- const size_t s = path.find_last_of("/\\");
7
- const std::string base = (s == std::string::npos) ? path : path.substr(s + 1);
8
- const size_t d = base.find_last_of('.');
9
- return (d == std::string::npos) ? base : base.substr(0, d);
10
- }
11
-
12
- // Gate verdict only (preview before staging). Dummy gate accepts everything.
13
- int driver_check(const std::string& src) {
14
- if (!gate_check(src)) { std::printf("gate.reject %s\n", src.c_str()); return EXIT_REJECT; }
15
- std::printf("gate.ok %s\n", src.c_str());
16
- return EXIT_OK;
17
- }
18
-
19
- // Enshell pipeline: frontend -> gate -> noising -> backend -> artifact. Emits
20
- // structured tokens on stdout; the Launcher renders them.
21
- int driver_enshell(const std::string& src) {
22
- const std::string base = stem(src), ir = base + ".ll", obj = base + ".o";
23
- if (!frontend_compile(src, ir)) { std::printf("frontend.failed %s\n", src.c_str()); return EXIT_ERR; }
24
- if (!gate_check(ir)) { std::remove(ir.c_str()); std::printf("gate.reject %s\n", src.c_str()); return EXIT_REJECT; }
25
- if (!noising_apply(ir)) { std::remove(ir.c_str()); std::printf("noising.failed %s\n", src.c_str()); return EXIT_ERR; }
26
- // baseline == transformed here (identity noising in place); real noising
27
- // yields a distinct transformed IR while the baseline is the L0 (pre-noise) IR.
28
- if (!harness_verify(ir, ir)) { std::remove(ir.c_str()); std::printf("verify.broken %s\n", src.c_str()); return EXIT_ERR; }
29
- if (!backend_emit(ir, obj)) { std::remove(ir.c_str()); std::printf("backend.failed %s\n", src.c_str()); return EXIT_ERR; }
30
- std::remove(ir.c_str());
31
- std::printf("sealed %s %s\n", src.c_str(), obj.c_str());
32
- return EXIT_OK;
33
- }
@@ -1,24 +0,0 @@
1
- #pragma once
2
- #include <string>
3
-
4
- // BlackShell engine — contract shared across the enshell pipeline.
5
- // The Driver sequences orthogonal primitives (load -> gate -> noise -> emit).
6
- // Each primitive lives in its own translation unit so a real implementation
7
- // drops in without touching the others (docs/Architecture.md §5).
8
- //
9
- // IR is handed between stages as a file path for now (clang/llc run as
10
- // subprocesses). shortcut: file-path handoff; upgrade to an in-memory IR handle
11
- // when the passes link libLLVM in-process.
12
-
13
- enum ExitCode { EXIT_OK = 0, EXIT_ERR = 1, EXIT_REJECT = 2 };
14
-
15
- // --- primitives (orthogonal; see frontend/gate/noising/backend .cpp) ---
16
- bool frontend_compile(const std::string& src, const std::string& ir_out); // clang: source -> IR
17
- bool gate_check(const std::string& ir); // §5 cond.1; dummy accept-all
18
- bool noising_apply(const std::string& ir); // L1-L3; dummy identity
19
- bool harness_verify(const std::string& baseline_ir, const std::string& transformed_ir); // EquivalenceHarness: L0 vs transformed; dummy = equivalent
20
- bool backend_emit(const std::string& ir, const std::string& obj_out); // llc: IR -> object
21
-
22
- // --- driver (sequences the primitives) ---
23
- int driver_check(const std::string& src); // gate verdict only
24
- int driver_enshell(const std::string& src); // full enshell pipeline
@@ -1 +0,0 @@
1
- int add2(int a, int b) { return a + b; }
@@ -1,10 +0,0 @@
1
- #include "engine.hpp"
2
- #include <cstdlib>
3
-
4
- // Frontend (LLVM / clang): compile source to LLVM IR. BLACK BOX — real LLVM.
5
- // shortcut: std::system with naive quoting (local dev tool, user's own files);
6
- // upgrade to CreateProcess/argv exec if quoting/injection matters.
7
- bool frontend_compile(const std::string& src, const std::string& ir_out) {
8
- const std::string cmd = "clang -S -emit-llvm \"" + src + "\" -o \"" + ir_out + "\"";
9
- return std::system(cmd.c_str()) == 0;
10
- }
@@ -1,5 +0,0 @@
1
- #include "engine.hpp"
2
-
3
- // Gate (our IP): §5 condition 1 isolation check (no external memory sharing).
4
- // DUMMY: accept-all. Real static analysis over the IR drops in here.
5
- bool gate_check(const std::string& /*ir*/) { return true; }
@@ -1,6 +0,0 @@
1
- #include "engine.hpp"
2
-
3
- // EquivalenceHarness (our IP · safety net): compile+run the baseline (L0) and
4
- // the transformed IR, compare observable outputs. DUMMY: always equivalent
5
- // (identity noising can't break anything yet). The real harness drops in here.
6
- bool harness_verify(const std::string& /*baseline_ir*/, const std::string& /*transformed_ir*/) { return true; }
@@ -1,17 +0,0 @@
1
- #include "engine.hpp"
2
- #include <cstdio>
3
- #include <string>
4
-
5
- // Entry point: parse the command and hand it to the Driver. The TS Launcher
6
- // owns real CLI parsing and message rendering; this is the engine's thin
7
- // dispatch, returning structured tokens on stdout (docs/Architecture.md §5).
8
- int main(int argc, char** argv) {
9
- if (argc < 2) { std::printf("usage\n"); return EXIT_OK; }
10
- const std::string cmd = argv[1];
11
- if (cmd == "check" || cmd == "enshell") {
12
- if (argc < 3) { std::printf("arg.one_positional\n"); return EXIT_ERR; }
13
- return (cmd == "check") ? driver_check(argv[2]) : driver_enshell(argv[2]);
14
- }
15
- std::printf("cmd.unknown %s\n", cmd.c_str());
16
- return EXIT_ERR;
17
- }
@@ -1,6 +0,0 @@
1
- #include "engine.hpp"
2
-
3
- // Noising (our IP): L1/L2 (OLLVM fork) + L3 (carry-sensitive MBA).
4
- // DUMMY: identity — the IR passes through untouched. Real passes link libLLVM
5
- // and transform the Module in place.
6
- bool noising_apply(const std::string& /*ir*/) { return true; }
@@ -1,249 +0,0 @@
1
- #!/usr/bin/env node
2
- // BlackShell Launcher (TS). Owns the CLI: parsing, the command set, the staging
3
- // index and message rendering (docs/Architecture.md §5 hybrid). The C++ engine
4
- // exposes per-unit primitives (check, enshell); the Launcher composes them — e.g.
5
- // `enshell` seals every staged unit by calling the engine's enshell per unit.
6
- import { spawnSync } from "node:child_process";
7
- import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
8
- import { fileURLToPath } from "node:url";
9
-
10
- const here = (p: string): string => fileURLToPath(new URL(p, import.meta.url));
11
- const pkg = JSON.parse(readFileSync(here("../package.json"), "utf8")) as { version: string };
12
-
13
- const USAGE = `blackshell <command> [options]
14
-
15
- check <source> Gate verdict only (dummy: accept-all)
16
- add <source> [--level L] Stage a unit for sealing (L = e.g. L1,L2; default L3)
17
- drop <source> Unstage a unit
18
- list Show staged units and their levels
19
- enshell Seal every staged unit -> object files
20
- help | -h Show this help
21
- -v | --version Show the version`;
22
-
23
- // --- staging index (.blackshell/stage.json in the working dir, git-index-like) ---
24
- const STAGE_FILE = ".blackshell/stage.json";
25
-
26
- interface Unit {
27
- path: string;
28
- levels: string[];
29
- }
30
-
31
- export function readStage(): Unit[] {
32
- if (!existsSync(STAGE_FILE)) {
33
- return [];
34
- }
35
- return JSON.parse(readFileSync(STAGE_FILE, "utf8")) as Unit[];
36
- }
37
-
38
- export function writeStage(units: Unit[]): void {
39
- mkdirSync(".blackshell", { recursive: true });
40
- writeFileSync(STAGE_FILE, JSON.stringify(units, null, 2) + "\n");
41
- }
42
-
43
- export function showLevels(levels: string[]): string {
44
- if (levels.length === 0) {
45
- return "L0 (identity)";
46
- }
47
- return levels.join(",");
48
- }
49
-
50
- // Resolve the engine binary: the published package ships a per-platform prebuilt
51
- // under vendor/<platform>-<arch>/; a local dev build lands in build/.
52
- function enginePath(): string {
53
- const exe = process.platform === "win32" ? "blackshell-engine.exe" : "blackshell-engine";
54
- const vendored = here(`../vendor/${process.platform}-${process.arch}/${exe}`);
55
- return existsSync(vendored) ? vendored : here(`../build/${exe}`);
56
- }
57
-
58
- // --- engine (C++) per-unit primitive call; returns the structured token line ---
59
- function engine(args: string[]): { token: string; status: number } {
60
- const bin = enginePath();
61
- const res = spawnSync(bin, args, { encoding: "utf8", stdio: ["inherit", "pipe", "inherit"] });
62
- if (res.error) {
63
- console.error("error: engine not found (build it: npm run build:engine)");
64
- return { token: "", status: 127 };
65
- }
66
- const token = (res.stdout ?? "").trim().split("\n").pop() ?? "";
67
- return { token, status: res.status ?? 1 };
68
- }
69
-
70
- // engine token -> rendered message. The engine never renders.
71
- export function render(token: string): { line: string; err: boolean } {
72
- const [key, ...a] = token.split(" ");
73
- switch (key) {
74
- case "gate.ok": {
75
- return { line: `pass: ${a[0]} is eligible`, err: false };
76
- }
77
- case "gate.reject": {
78
- return { line: `reject: ${a[0]} — ineligible`, err: true };
79
- }
80
- case "sealed": {
81
- return { line: `sealed: ${a[0]} -> ${a[1]}`, err: false };
82
- }
83
- case "frontend.failed": {
84
- return { line: `error: clang (frontend) failed on ${a[0]}`, err: true };
85
- }
86
- case "backend.failed": {
87
- return { line: `error: llc (backend) failed on ${a[0]}`, err: true };
88
- }
89
- case "verify.broken": {
90
- return { line: `error: noising broke equivalence on ${a[0]}`, err: true };
91
- }
92
- case "arg.one_positional": {
93
- return { line: `error: expected exactly one <source> argument`, err: true };
94
- }
95
- case "cmd.unknown": {
96
- return { line: `error: unknown command: ${a[0]}`, err: true };
97
- }
98
- default: {
99
- return { line: token, err: true };
100
- }
101
- }
102
- }
103
-
104
- function emit(token: string): void {
105
- if (!token) {
106
- return;
107
- }
108
- const { line, err } = render(token);
109
- if (err) {
110
- console.error(line);
111
- } else {
112
- console.log(line);
113
- }
114
- }
115
-
116
- // --- arg helpers ---
117
- export function popOption(rest: string[], name: string): { value: string | undefined; rest: string[] } {
118
- const i = rest.indexOf(name);
119
- if (i === -1) {
120
- return { value: undefined, rest };
121
- }
122
- return { value: rest[i + 1], rest: rest.slice(0, i).concat(rest.slice(i + 2)) };
123
- }
124
-
125
- export function onePositional(rest: string[]): string | undefined {
126
- const positionals = rest.filter((a) => !a.startsWith("--"));
127
- if (positionals.length !== 1) {
128
- return undefined;
129
- }
130
- return positionals[0];
131
- }
132
-
133
- // --- commands ---
134
- function cmdCheck(rest: string[]): number {
135
- const src = onePositional(rest);
136
- if (src === undefined) {
137
- console.error("error: expected exactly one <source> argument");
138
- return 1;
139
- }
140
- const { token, status } = engine(["check", src]);
141
- emit(token);
142
- return status;
143
- }
144
-
145
- function cmdAdd(rest: string[]): number {
146
- const opt = popOption(rest, "--level");
147
- const src = onePositional(opt.rest);
148
- if (src === undefined) {
149
- console.error("error: expected exactly one <source> argument");
150
- return 1;
151
- }
152
- if (!existsSync(src)) {
153
- console.error(`error: file not found: ${src}`);
154
- return 1;
155
- }
156
- const levels = opt.value ? opt.value.split(",").map((s) => s.trim()).filter(Boolean) : ["L3"];
157
- const units = readStage().filter((u) => u.path !== src);
158
- units.push({ path: src, levels });
159
- writeStage(units);
160
- console.log(`staged: ${src} [${showLevels(levels)}]`);
161
- return 0;
162
- }
163
-
164
- function cmdDrop(rest: string[]): number {
165
- const src = onePositional(rest);
166
- if (src === undefined) {
167
- console.error("error: expected exactly one <source> argument");
168
- return 1;
169
- }
170
- const units = readStage();
171
- const kept = units.filter((u) => u.path !== src);
172
- if (kept.length === units.length) {
173
- console.error(`error: not staged: ${src}`);
174
- return 1;
175
- }
176
- writeStage(kept);
177
- console.log(`dropped: ${src}`);
178
- return 0;
179
- }
180
-
181
- function cmdList(): number {
182
- const units = readStage();
183
- if (units.length === 0) {
184
- console.log("nothing staged");
185
- return 0;
186
- }
187
- for (const u of units) {
188
- console.log(` ${u.path} [${showLevels(u.levels)}]`);
189
- }
190
- return 0;
191
- }
192
-
193
- function cmdEnshell(): number {
194
- const units = readStage();
195
- if (units.length === 0) {
196
- console.log("nothing staged");
197
- return 0;
198
- }
199
- let code = 0;
200
- for (const u of units) {
201
- const { token, status } = engine(["enshell", u.path]);
202
- emit(token);
203
- if (status !== 0) {
204
- code = status;
205
- }
206
- }
207
- writeStage([]); // 1-shot: staging is consumed by enshell
208
- console.log(`enshell complete: ${units.length} unit(s); staging cleared`);
209
- return code;
210
- }
211
-
212
- function main(argv: string[]): number {
213
- const [cmd, ...rest] = argv;
214
- if (cmd === "-v" || cmd === "--version" || cmd === "version") {
215
- console.log(pkg.version);
216
- return 0;
217
- }
218
- if (cmd === undefined || cmd === "help" || cmd === "-h" || cmd === "--help") {
219
- console.log(USAGE);
220
- return 0;
221
- }
222
- switch (cmd) {
223
- case "check": {
224
- return cmdCheck(rest);
225
- }
226
- case "add": {
227
- return cmdAdd(rest);
228
- }
229
- case "drop": {
230
- return cmdDrop(rest);
231
- }
232
- case "list": {
233
- return cmdList();
234
- }
235
- case "enshell": {
236
- return cmdEnshell();
237
- }
238
- default: {
239
- console.error(`error: unknown command: ${cmd}`);
240
- console.error(USAGE);
241
- return 1;
242
- }
243
- }
244
- }
245
-
246
- // Run only when invoked directly (not when imported by tests).
247
- if (process.argv[1] === fileURLToPath(import.meta.url)) {
248
- process.exit(main(process.argv.slice(2)));
249
- }
Binary file
Binary file