@tungcorn/spacelens 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tungcorn
+
+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,75 @@
+# @tungcorn/spacelens
+
+SpaceLens is native C++ storage intelligence for Windows.
+
+This npm package is an installation channel. It contains the complete
+v0.1.1 distribution: the desktop GUI and the read-only CLI, plus the Qt
+6.8.3 runtime those binaries need. Node and npm are required only to
+install and launch this package. SpaceLens itself remains native C++.
+
+This is not a Node SDK. The wrappers do not add commands, transform
+JSON, or authorize filesystem maintenance.
+
+## Requirements
+
+- Windows x64 only (`os: win32`, `cpu: x64`)
+- Node.js 18+ (for the launchers)
+- [Microsoft Visual C++ Redistributable (x64)](https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist)
+
+Binaries are unsigned.
+
+## Install
+
+```text
+npm install -g @tungcorn/spacelens
+```
+
+The tarball already includes the native runtime. Installation does not
+download further GitHub or npm assets.
+
+## Commands
+
+```text
+spacelens
+spacelens-gui
+```
+
+CLI examples (real verbs from SpaceLens v0.1.1):
+
+```text
+spacelens version
+spacelens help
+spacelens capabilities --json
+spacelens scan C:\path\to\folder --json
+spacelens top C:\path\to\folder --json
+```
+
+`spacelens ... --json` is safe for scripts and agents: the launcher
+prints no banner and does not rewrite native stdout.
+
+## Safety
+
+The CLI is read-only.
+
+```text
+spacelens capabilities --json
+```
+
+reports `filesystem_mutation: false`.
+
+The CLI cannot recycle, restore, delete, move, or declare locations.
+Filesystem maintenance remains GUI-only and explicitly human-authorized
+(Recycle Bin, after confirmation). The npm wrapper exposes no mutation
+API.
+
+Uninstalling the npm package removes the staged binaries and shims. It
+does not delete `%LOCALAPPDATA%\SpaceLens\` (indexes, review state,
+maintenance history).
+
+## License
+
+SpaceLens-owned files are MIT. See `LICENSE`.
+
+Qt remains under its own licenses (LGPL-3.0-only option for this
+dynamic build). Qt is not MIT. Corresponding-source identity and the
+written offer are in `licenses/`.

package/bin/launch.js

@@ -0,0 +1,88 @@
+'use strict';
+
+const { spawnSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+function packageRootFromBinDir(binDir) {
+  return path.join(binDir, '..');
+}
+
+function resolveNative(fileName, rootDir) {
+  if (typeof fileName !== 'string' || fileName.length === 0) {
+    throw new Error('native file name is required');
+  }
+  if (fileName !== path.basename(fileName) || /[\\/]/.test(fileName)) {
+    throw new Error('native file name must be a basename');
+  }
+  return path.join(rootDir, 'native', fileName);
+}
+
+function missingMessage(exePath) {
+  return `spacelens: native executable not found: ${exePath}\n`;
+}
+
+function runNative(fileName, argv, options) {
+  const opts = options || {};
+  const rootDir = opts.packageRoot || packageRootFromBinDir(__dirname);
+  const exePath = opts.nativePath || resolveNative(fileName, rootDir);
+  const stdio = opts.stdio || 'inherit';
+  const args = Array.isArray(argv) ? argv : [];
+
+  if (!fs.existsSync(exePath)) {
+    const stderr = missingMessage(exePath);
+    if (stdio !== 'pipe') {
+      process.stderr.write(stderr);
+    }
+    return {
+      status: 1,
+      signal: null,
+      stdout: '',
+      stderr,
+      error: new Error('native executable not found'),
+      exePath,
+    };
+  }
+
+  const result = spawnSync(exePath, args, {
+    stdio,
+    shell: false,
+    windowsHide: false,
+    encoding: stdio === 'pipe' ? opts.encoding || 'utf8' : undefined,
+  });
+
+  if (result.error) {
+    const stderr = `spacelens: failed to start native executable: ${result.error.message}\n`;
+    if (stdio !== 'pipe') {
+      process.stderr.write(stderr);
+    }
+    return {
+      status: 1,
+      signal: null,
+      stdout: result.stdout || '',
+      stderr: `${result.stderr || ''}${stderr}`,
+      error: result.error,
+      exePath,
+    };
+  }
+
+  return {
+    status: result.status === null ? 1 : result.status,
+    signal: result.signal,
+    stdout: result.stdout || '',
+    stderr: result.stderr || '',
+    error: null,
+    exePath,
+  };
+}
+
+function exitWithNative(fileName, argv) {
+  return runNative(fileName, argv, { stdio: 'inherit' }).status;
+}
+
+module.exports = {
+  packageRootFromBinDir,
+  resolveNative,
+  runNative,
+  exitWithNative,
+};

package/bin/spacelens-gui.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+'use strict';
+
+const { exitWithNative } = require('./launch.js');
+
+process.exit(exitWithNative('spacelens-gui.exe', process.argv.slice(2)));

package/bin/spacelens.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+'use strict';
+
+const { exitWithNative } = require('./launch.js');
+
+process.exit(exitWithNative('spacelens.exe', process.argv.slice(2)));