usesprocket 0.0.0 → 0.4.3-dev.efb29f1a00a6702afbc7d21c6e442e2d4635cec9

package/LICENSE

@@ -0,0 +1,112 @@
+# Functional Source License, Version 1.1, ALv2 Future License
+
+## Abbreviation
+
+FSL-1.1-ALv2
+
+## Notice
+
+Copyright 2026 Aarav Gupta
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the Apache License, Version 2.0 that is effective on the second anniversary of
+the date we make the Software available. On or after that date, you may use the
+Software under the Apache License, Version 2.0, in which case the following
+will apply:
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License.
+
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.
+
+---
+
+## Third-party material
+
+This license does not replace the licenses for third-party material included in Sprocket.
+See [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) for those licenses and copyright notices.

package/README.md

@@ -1,3 +1,58 @@
-# usesprocket
+# Sprocket
 
-Placeholder for [Sprocket](https://github.com/spikonado/sprocket). The first release replaces this version.
+The best AI agent for hardware and software.
+
+Sprocket designs electronics, tests code end-to-end, and buys parts or subscriptions for your project when asked.
+
+[![Sprocket](./assets/sprocket.webp)](https://spikonado.com/sprocket)
+
+## Using Sprocket
+
+### Desktop app
+
+Download the installer for your OS from the [latest release](https://github.com/spikonado/sprocket/releases/latest), install it, and open Sprocket. Sign in, choose a project folder, and ask Sprocket what you'd like to build.
+
+### Run without installing
+
+With [Node.js](https://nodejs.org/) 20.11 or newer installed:
+
+```sh
+npx usesprocket
+```
+
+This opens Sprocket in your browser, or in the desktop app if it's installed. Sign in and choose a project folder to get started. Add `--web` to always use your browser.
+
+### CLI
+
+```sh
+npm install -g usesprocket
+sprocket
+```
+
+Open a project folder in the app, or force it to open in your browser:
+
+```sh
+sprocket .
+sprocket --web ../my-robot
+```
+
+To run a task directly from your terminal, run these commands in your project folder:
+
+```sh
+sprocket login
+sprocket run "Fix the failing tests"
+```
+
+Update your CLI installation with `sprocket update`. Run `sprocket --help` for more options.
+
+## Troubleshooting
+
+- If `17731` is already occupied, set `SPROCKET_PORT` before launching.
+- Sprocket uses your operating system credential service when available, and automatically falls back to an unencrypted private file when it is unavailable. Use `sprocket login --credential-store keyring` to require keyring storage, or `sprocket login --credential-store file` to require file storage.
+- If `sprocket` opens the browser instead of the desktop app, install `sprocket-desktop` from [GitHub Releases](https://github.com/spikonado/sprocket/releases) onto `PATH`, or set `SPROCKET_DESKTOP_EXECUTABLE`.
+- Unsigned macOS and Windows desktop builds may need a Gatekeeper / SmartScreen override the first time you open them.
+- Contact [aarav@spikonado.com](mailto:aarav@spikonado.com) for help.
+
+## License
+
+Sprocket is licensed under the [Functional Source License, Version 1.1, ALv2 Future License](LICENSE.md). Third-party material remains under the licenses listed in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,80 @@
+# Third-party notices
+
+## Managed browser tools
+
+Sprocket downloads unmodified native releases of
+[agent-browser](https://github.com/vercel-labs/agent-browser) on demand. It is
+copyright Vercel, Inc., and licensed under
+[Apache-2.0](https://github.com/vercel-labs/agent-browser/blob/main/LICENSE).
+When serving agent-browser's dashboard, Sprocket changes its web assets to
+offer only Chrome and hide AI chat, as listed in
+`tools/agent-browser/dashboard-patches.json`.
+
+Versions, release asset sizes, and SHA256 checksums are recorded in
+`tools/agent-browser/releases.json`. Chromium downloaded by the
+upstream installer retains its own third-party licenses and notices.
+
+## Bun
+
+Sprocket downloads unmodified releases of [Bun](https://github.com/oven-sh/bun)
+on demand. Bun is licensed under
+[MIT](https://github.com/oven-sh/bun/blob/main/LICENSE.md) and statically links
+libraries under their own licenses, including JavaScriptCore under LGPL-2.
+
+The Bun version, archive sizes, and SHA256 checksums are recorded in
+`tools/bun/releases.json`.
+
+## agent-desktop
+
+Sprocket downloads unmodified native releases of
+[agent-desktop](https://github.com/vercel-labs/agent-desktop) on demand. It is
+copyright Vercel, Inc., and licensed under
+[Apache-2.0](https://github.com/vercel-labs/agent-desktop/blob/main/LICENSE).
+
+The agent-desktop version, archive sizes, and SHA256 checksums are recorded in
+`tools/agent-desktop/releases.json`.
+
+## uv and Python
+
+Sprocket downloads unmodified releases of [uv](https://github.com/astral-sh/uv)
+on demand. uv is licensed under
+[MIT](https://github.com/astral-sh/uv/blob/main/LICENSE-MIT) or
+[Apache-2.0](https://github.com/astral-sh/uv/blob/main/LICENSE-APACHE). The uv
+version, archive sizes, and SHA256 checksums are recorded in
+`tools/uv/releases.json`.
+
+uv then installs a [python-build-standalone](https://github.com/astral-sh/python-build-standalone)
+build of CPython, which is licensed under the
+[PSF License](https://docs.python.org/3/license.html) and bundles libraries
+under their own licenses.
+
+## KiCad
+
+The KiCad connector downloads [KiCad](https://www.kicad.org) nightly builds
+when the user installs it. KiCad is licensed under
+[GPL-3.0-or-later](https://gitlab.com/kicad/code/kicad/-/blob/master/LICENSE.GPLv3),
+and its bundled symbol, footprint, and 3D model libraries are licensed under
+[CC-BY-SA-4.0 with an exception](https://www.kicad.org/libraries/license/) for
+designs made with them. The builds are unmodified upstream files mirrored to a
+`kicad-<version>` release of this repository, whose notes link the exact KiCad
+source commit.
+
+The same release holds a wheel of
+[kicad-python](https://gitlab.com/kicad/code/kicad-python), licensed under
+[MIT](https://gitlab.com/kicad/code/kicad-python/-/blob/main/LICENSE), built
+with `tools/kicad/kipy-cli-env.patch`, and per-platform archives of
+[KiCadRoutingTools](https://github.com/drandyhaas/KiCadRoutingTools), licensed
+under [MIT](https://github.com/drandyhaas/KiCadRoutingTools/blob/main/LICENSE),
+with `tools/kicad/routing-tools-transform-pose.patch` applied and its example
+boards removed. Their Python dependencies keep their own licenses. The KiCad
+version, file sizes, and SHA256 checksums are recorded in
+`tools/kicad/releases.json`, and the dependencies' hashes in
+`tools/kicad/requirements.txt`.
+
+## KiCanvas
+
+The web app ships a build of [KiCanvas](https://github.com/theacodes/kicanvas)
+in `apps/web/static/kicanvas/`, made by `tools/kicanvas/build.sh` from the
+commit it pins, with the patches next to that script. KiCanvas is copyright
+Alethea Katherine Flowers and licensed under MIT; its license is next to the
+build. When it opens a file, it loads its icon and text fonts from Google Fonts.

package/bin/sprocket.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { launch } from '../lib/launcher.js';
+
+await launch(process.argv.slice(2));

package/lib/launcher.js

@@ -0,0 +1,179 @@
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { accessSync, chmodSync, constants, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+import { resolveNativePackage } from './native.js';
+import {
+	createHost,
+	PACKAGE_ROOT,
+	parseUpdateArgs,
+	runUpdateCli,
+	UPDATE_API_FILENAME
+} from './update.js';
+
+export function resolveNativeBinary() {
+	const native = resolveNativePackage();
+	const version = JSON.parse(readFileSync(path.join(PACKAGE_ROOT, 'package.json'), 'utf8')).version;
+
+	if (native.version !== version) {
+		throw new Error(
+			`Sprocket ${version} needs ${native.packageName}@${version}, but ${native.version} is ` +
+				'installed. Run `sprocket update` to repair the install.'
+		);
+	}
+
+	return native.binary;
+}
+
+export function ensureExecutable(binary) {
+	if (process.platform === 'win32') {
+		return;
+	}
+
+	try {
+		accessSync(binary, constants.X_OK);
+	} catch {
+		try {
+			chmodSync(binary, 0o755);
+		} catch {
+			// Best-effort; spawn reports EACCES if still unusable.
+		}
+	}
+}
+
+export async function run(binary, args, options = {}) {
+	const child = (options.spawn ?? spawn)(binary, args, {
+		stdio: 'inherit',
+		env: options.env ?? process.env
+	});
+
+	let interrupted;
+
+	const handlers = new Map(
+		['SIGINT', 'SIGTERM'].map((signal) => [
+			signal,
+			() => {
+				interrupted ??= signal;
+
+				// Windows already sends Ctrl+C to both processes; child.kill would force termination.
+				if (process.platform !== 'win32' || signal !== 'SIGINT') {
+					child.kill(signal);
+				}
+			}
+		])
+	);
+
+	for (const [signal, handler] of handlers) {
+		process.on(signal, handler);
+	}
+
+	let result;
+
+	try {
+		result = await new Promise((resolve, reject) => {
+			child.once('error', reject);
+			child.once('close', (status, signal) => resolve({ status, signal }));
+		});
+	} finally {
+		for (const [signal, handler] of handlers) {
+			process.off(signal, handler);
+		}
+	}
+
+	const signal = result.signal ?? interrupted;
+
+	if (signal) {
+		process.kill(process.pid, signal);
+
+		return undefined;
+	}
+
+	return result.status ?? 1;
+}
+
+export function nativeChildEnvironment(env, staticDir, updateNode, updateScript) {
+	const next = {
+		...env,
+		SPROCKET_STATIC_DIR: env.SPROCKET_STATIC_DIR || staticDir,
+		SPROCKET_UPDATE_NODE: updateNode,
+		SPROCKET_UPDATE_SCRIPT: updateScript
+	};
+
+	delete next.SPROCKET_UPDATE_MANAGED;
+
+	return next;
+}
+
+function readRestartLauncher(restartFile) {
+	try {
+		return readFileSync(restartFile, 'utf8');
+	} catch {
+		return null;
+	} finally {
+		rmSync(restartFile, { force: true });
+	}
+}
+
+export async function launch(args, options = {}) {
+	const env = { ...(options.env ?? process.env) };
+	delete env.SPROCKET_UPDATE_MANAGED;
+	const parsed = parseUpdateArgs(args);
+
+	if (parsed.kind !== 'none' && parsed.kind !== 'native') {
+		const code = await runUpdateCli(parsed, options.host ?? createHost({ env }));
+		process.exitCode = code;
+
+		return code;
+	}
+
+	try {
+		const libDir = options.libDir ?? import.meta.dirname;
+		const staticDir = path.resolve(libDir, '../web');
+		const binary = (options.resolveBinary ?? resolveNativeBinary)();
+		(options.ensureExecutable ?? ensureExecutable)(binary);
+		const execPath = options.execPath ?? process.execPath;
+		// The native server clears SPROCKET_RESTARTED, so only a launcher started by a restarting
+		// launcher sees it and leaves the next restart to that parent.
+		const ownsRestart = !env.SPROCKET_RESTARTED;
+
+		if (ownsRestart) {
+			env.SPROCKET_RESTART_FILE = path.join(
+				options.tmpdir ?? tmpdir(),
+				`sprocket-restart-${randomUUID()}`
+			);
+		}
+
+		let code = await run(binary, args, {
+			env: nativeChildEnvironment(
+				env,
+				staticDir,
+				execPath,
+				path.resolve(libDir, UPDATE_API_FILENAME)
+			),
+			spawn: options.spawn
+		});
+
+		if (ownsRestart) {
+			for (;;) {
+				const launcher = readRestartLauncher(env.SPROCKET_RESTART_FILE);
+
+				if (!launcher) break;
+				code = await run(execPath, [launcher, ...args], {
+					env: { ...env, SPROCKET_RESTARTED: '1' },
+					spawn: options.spawn
+				});
+			}
+		}
+
+		process.exitCode = code;
+
+		return process.exitCode;
+	} catch (error) {
+		console.error(`sprocket: ${error.message}`);
+		process.exitCode = 1;
+
+		return 1;
+	}
+}

package/lib/native.js

@@ -0,0 +1,57 @@
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+
+const require = createRequire(import.meta.url);
+
+const TARGETS = JSON.parse(readFileSync(path.join(import.meta.dirname, '../targets.json'), 'utf8'));
+
+const PLATFORM_PACKAGES = new Map(
+	TARGETS.map((target) => [`${target.os}:${target.cpu}`, [target.packageName, target.executable]])
+);
+
+export function nativePackage(platform = process.platform, arch = process.arch) {
+	return PLATFORM_PACKAGES.get(`${platform}:${arch}`);
+}
+
+export function resolveNativePackage(platform = process.platform, arch = process.arch) {
+	const target = nativePackage(platform, arch);
+
+	if (!target) {
+		throw new Error(
+			`Sprocket does not provide a binary for ${platform}/${arch}. ` +
+				'Supported targets are Linux x64/arm64, macOS x64/arm64, and Windows x64.'
+		);
+	}
+
+	const [packageName, executable] = target;
+	let packageJson;
+
+	try {
+		packageJson = require.resolve(`${packageName}/package.json`);
+	} catch (error) {
+		if (error?.code !== 'MODULE_NOT_FOUND') {
+			throw error;
+		}
+
+		throw new Error(
+			`The native package ${packageName} is missing. Reinstall Sprocket ` +
+				'without omitting optional dependencies.',
+			{ cause: error }
+		);
+	}
+
+	return {
+		packageName,
+		version: JSON.parse(readFileSync(packageJson, 'utf8')).version,
+		binary: path.join(path.dirname(packageJson), 'bin', executable)
+	};
+}
+
+export function installedNativeVersion() {
+	try {
+		return resolveNativePackage().version;
+	} catch {
+		return '';
+	}
+}

package/lib/update-api.js

@@ -0,0 +1,7 @@
+import { runUpdateApi } from './update.js';
+
+const { exitCode, payload } = await runUpdateApi(process.argv[2]);
+
+process.stdout.write(`${JSON.stringify(payload)}\n`);
+
+process.exitCode = exitCode;