@vforsh/argus 0.1.18 → 0.1.19

package/dist/skill/argus/reference/START.md

@@ -0,0 +1,120 @@
+## Start And Watcher Lifecycle
+
+Use CDP startup when an isolated/debuggable Chrome is acceptable. Use extension-control instead when the task needs the user's normal browser profile, cookies, local storage, saved logins, or already-open tabs.
+
+Long-running commands must run in the background in agent shells:
+
+- `argus start`
+- `argus chrome start`
+- `argus watcher start`
+- `argus logs tail`
+- `argus net tail`
+
+## Start (Chrome + Watcher)
+
+```bash
+argus start --id app --url localhost:3000
+argus start --id app --auth-from extension-2
+argus start --id app --auth-from extension-2 --url https://target.app/
+argus start --id app --url localhost:3000 --dev-tools
+argus start --id app --url localhost:3000 --profile temp
+argus start --id app --type page --headless
+argus start --id app --url localhost:3000 --inject ./debug.js
+argus start --id app --url localhost:3000 --no-page-indicator
+argus start --id app --url localhost:3000 --json
+```
+
+`--url` opens in Chrome and matches the watcher target. `--auth-from` clones cookies and storage from another watcher into a fresh temp Chrome session before attach; add `--url` to override the final destination after hydration. `argus start` accepts Chrome options (`--profile`, `--dev-tools`, `--headless`) and watcher options (`--type`, `--origin`, `--target`, `--parent`, `--inject`, `--artifacts`, `--no-page-indicator`).
+
+## Chrome Start
+
+```bash
+argus chrome start --url http://localhost:3000
+argus chrome start --from-watcher app
+argus chrome start --dev-tools
+argus chrome start --headless
+argus chrome start --auth-state auth.json
+```
+
+`--from-watcher` reads the URL from a registered watcher config. `--auth-state` hydrates cookies/storage into a fresh Chrome profile before opening the page.
+
+## Watcher Start
+
+```bash
+argus watcher start --id app --url localhost:3000
+argus watcher start --id app --url localhost:3000 --chrome-port 9222
+argus watcher start --id app --type iframe --url localhost:3007
+argus watcher start --id app --type iframe --parent example.com
+argus watcher start --id app --origin https://localhost:3007
+argus watcher start --id app --target CC1135709D9AC3B9CC0446F8B58CC344
+argus watcher start --id app --url localhost:3000 --inject ./debug.js
+argus watcher start --id app --url localhost:3000 --no-page-indicator
+argus watcher start --id app --source extension
+```
+
+`--url` matches a target URL substring. `--origin` matches protocol+host+port. `--target` connects to a specific Chrome target id. `--type` filters target type (`page`, `iframe`, `worker`). `--parent` filters by parent target URL. `--inject` runs a JS file on attach and navigation. `--no-page-indicator` hides the in-page overlay, useful before screenshots.
+
+## Targets / Pages
+
+```bash
+argus page ls --id app
+argus page ls --type iframe --id app
+argus page ls --tree --id app
+argus page open --url http://example.com --id app
+argus page reload --id app
+argus page reload <targetId> --param foo=bar
+argus page activate <targetId>
+argus page close <targetId>
+argus reload app
+argus reload app --ignore-cache
+```
+
+## Config Defaults
+
+Load defaults for `argus start`, `argus chrome start`, and `argus watcher start` from config files.
+
+Auto-discovery:
+
+- `.argus/config.json`
+- `.config/argus.json`
+- `argus.config.json`
+- `argus/config.json`
+
+```json
+{
+	"chrome": {
+		"start": { "url": "http://localhost:3000", "devTools": true }
+	},
+	"watcher": {
+		"start": {
+			"id": "app",
+			"url": "localhost:3000",
+			"chromePort": 9222,
+			"artifacts": "./artifacts",
+			"inject": { "file": "./scripts/debug.js" }
+		}
+	}
+}
+```
+
+CLI flags override config. `argus config init` creates a starter config. Script injection runs custom JS on attach and page navigation; see [INJECT.md](./INJECT.md).
+
+## Programmatic Watcher (Node API)
+
+Use `@vforsh/argus-watcher` to create watchers from code.
+
+```js
+import { startWatcher } from '@vforsh/argus-watcher'
+
+const { watcher, events, close } = await startWatcher({
+	id: 'app',
+	match: { url: 'localhost:3000' },
+	chrome: { host: '127.0.0.1', port: 9222 },
+})
+
+events.on('cdpAttached', ({ target }) => {
+	console.log(`Attached to ${target?.title}`)
+})
+
+await close()
+```

package/dist/skill/argus/start-watcher.ts

@@ -0,0 +1,108 @@
+/**
+ * Example: start an Argus watcher programmatically via `@vforsh/argus-watcher`.
+ */
+
+import { startWatcher } from '@vforsh/argus-watcher'
+
+const main = async (): Promise<void> => {
+	const id = process.env.WATCHER_ID ?? 'app'
+	const matchUrl = process.env.MATCH_URL ?? 'localhost:3000'
+
+	const chromeHost = process.env.CHROME_HOST ?? '127.0.0.1'
+	const chromePort = parsePort(process.env.CHROME_PORT, 9222)
+
+	const bindHost = process.env.WATCHER_HOST ?? '127.0.0.1'
+	const bindPort = parsePort(process.env.WATCHER_PORT, 0)
+
+	const artifactsBase = process.env.ARTIFACTS_BASE
+	const fileLogsEnabled = parseBool(process.env.FILE_LOGS_ENABLED, false)
+
+	const { watcher, events, close } = await startWatcher({
+		id,
+		match: { url: matchUrl },
+		chrome: { host: chromeHost, port: chromePort },
+		host: bindHost,
+		port: bindPort,
+		artifacts: artifactsBase
+			? {
+					base: artifactsBase,
+					logs: { enabled: fileLogsEnabled },
+				}
+			: { logs: { enabled: fileLogsEnabled } },
+	})
+
+	console.log(`Watcher started: id=${watcher.id} url=http://${watcher.host}:${watcher.port}`)
+
+	events.on('cdpAttached', ({ target }) => {
+		console.log(`CDP attached: ${target?.title ?? '(unknown title)'} ${target?.url ?? ''}`.trim())
+	})
+
+	events.on('cdpDetached', ({ reason }) => {
+		console.log(`CDP detached: ${reason}`)
+	})
+
+	installShutdownHandlers(async () => {
+		console.log('Shutting down watcher...')
+		await close()
+	})
+}
+
+const parsePort = (raw: string | undefined, fallback: number): number => {
+	if (raw === undefined || raw === null || raw.trim() === '') {
+		return fallback
+	}
+
+	const n = Number(raw)
+	if (!Number.isInteger(n) || n < 0 || n > 65535) {
+		throw new Error(`Invalid port: ${raw}`)
+	}
+
+	return n
+}
+
+const parseBool = (raw: string | undefined, fallback: boolean): boolean => {
+	if (raw === undefined || raw === null || raw.trim() === '') {
+		return fallback
+	}
+
+	switch (raw.trim().toLowerCase()) {
+		case '1':
+		case 'true':
+		case 'yes':
+		case 'y':
+		case 'on':
+			return true
+		case '0':
+		case 'false':
+		case 'no':
+		case 'n':
+		case 'off':
+			return false
+		default:
+			throw new Error(`Invalid boolean: ${raw}`)
+	}
+}
+
+const installShutdownHandlers = (shutdown: () => Promise<void>): void => {
+	let closed = false
+	const closeOnce = async () => {
+		if (closed) {
+			return
+		}
+		closed = true
+		await shutdown()
+	}
+
+	process.once('SIGINT', () => void closeOnce())
+	process.once('SIGTERM', () => void closeOnce())
+	process.once('uncaughtException', (err) => {
+		console.error(err)
+		void closeOnce()
+	})
+	process.once('unhandledRejection', (err) => {
+		console.error(err)
+		void closeOnce()
+	})
+}
+
+await main()

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vforsh/argus",
-	"version": "0.1.18",
+	"version": "0.1.19",
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/vforsh/argus.git",
@@ -36,7 +36,7 @@
 	"scripts": {
 		"clean": "node ../../scripts/clean-dist.mjs",
 		"build": "npm run clean && tsc -b && bun run bundle",
-		"bundle": "bun build dist/bin.js --outfile dist/argus.js --target node --external esbuild",
+		"bundle": "bun build dist/bin.js --outfile dist/argus.js --target node --external esbuild && node ../../scripts/copy-argus-skill.mjs",
 		"typecheck": "tsc -b --pretty false",
 		"chrome:start": "bun src/bin.ts chrome start"
 	}