open-index/open-npm huggingface dataset:
npm package: @grackle-ai/adapter-local
Description: Grackle local environment adapter
Latest version: 0.108.0

# @grackle-ai/adapter-local

<p align="center">
  <a href="https://www.npmjs.com/package/@grackle-ai/adapter-local"><img src="https://img.shields.io/npm/v/@grackle-ai/adapter-local.svg" alt="npm version" /></a>
  <a href="https://github.com/nick-pape/grackle/actions/workflows/ci.yml"><img src="https://github.com/nick-pape/grackle/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI" /></a>
  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT" /></a>
</p>

<p align="center">
  <img src="https://raw.githubusercontent.com/nick-pape/grackle/main/apps/docs-site/static/img/grackle-logo.png" alt="Grackle" width="200" />
</p>

Grackle environment adapter for connecting to a locally-running PowerLine process.

## Overview

The local adapter connects to a PowerLine gRPC server on the same machine. It is the simplest adapter — no tunneling, no remote provisioning.

## Configuration

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `port` | `number` | `7433` | PowerLine port |
| `host` | `string` | `"localhost"` | PowerLine host |

## Prerequisites

- A locally-running PowerLine process (typically managed by the Grackle server)
npm package: @grackle-ai/auth
Description: Authentication and authorization primitives for Grackle
Latest version: 0.108.0

# @grackle-ai/auth

<p align="center">
  <a href="https://www.npmjs.com/package/@grackle-ai/auth"><img src="https://img.shields.io/npm/v/@grackle-ai/auth.svg" alt="npm version" /></a>
  <a href="https://github.com/nick-pape/grackle/actions/workflows/ci.yml"><img src="https://github.com/nick-pape/grackle/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI" /></a>
  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT" /></a>
</p>

<p align="center">
  <img src="https://raw.githubusercontent.com/nick-pape/grackle/main/apps/docs-site/static/img/grackle-logo.png" alt="Grackle" width="200" />
</p>

Authentication and authorization primitives for [Grackle](https://github.com/nick-pape/grackle).

## Features

- **API key management** — Generate, persist, and verify 256-bit API keys with constant-time comparison
- **Browser sessions** — HMAC-signed cookie sessions with automatic expiry and cleanup
- **Pairing codes** — Time-limited 6-character codes with IP-based rate limiting for device pairing
- **OAuth 2.1** — Dynamic client registration, PKCE (S256), authorization codes, and refresh token rotation
- **HMAC-signed tokens** — OAuth access tokens and scoped task tokens for MCP authentication
- **MCP request auth** — Middleware that authenticates API key, OAuth, and scoped token bearers
- **Security headers** — CSP and defense-in-depth headers for HTTP responses

## Logger Configuration

Auth modules use a pluggable logger. Call `setAuthLogger()` at startup to inject your application logger:

```typescript
import { setAuthLogger } from "@grackle-ai/auth";
import { logger } from "./my-logger.js";

setAuthLogger(logger);
```

If not configured, a default console-based logger is used.
npm package: @grackle-ai/database
Description: SQLite persistence layer for Grackle — schema, stores, and migrations
Latest version: 0.108.0

# @grackle-ai/database

SQLite persistence layer for Grackle — schema definitions, store modules, migrations, and encrypted token storage.

## What it provides

- **Schema** — Drizzle ORM table definitions for environments, sessions, tasks, workspaces, findings, personas, settings, tokens, and domain events
- **Stores** — Focused CRUD modules for each entity (e.g., `sessionStore`, `taskStore`, `workspaceStore`)
- **Migrations** — Idempotent schema migrations that run on every startup
- **Seeding** — Application-level defaults (personas, root task, settings backfills)
- **Crypto** — AES-256-GCM encryption for token storage

## Usage

```typescript
import { openDatabase, initDatabase, seedDatabase, sqlite, sessionStore } from "@grackle-ai/database";

// Initialize at startup
openDatabase();
initDatabase();
seedDatabase(sqlite!);

// Use stores
const session = sessionStore.getSession("session-123");
```

## Requirements

- Node.js >= 22
- `better-sqlite3` native module (built at install time)

## License

MIT
npm package: @grackle-ai/plugin-orchestration
Description: Orchestration plugin for Grackle — tasks, personas, findings, and escalations
Latest version: 0.108.0

# @grackle-ai/plugin-orchestration

Orchestration plugin for Grackle — tasks, personas, findings, and escalations.

Separating orchestration from core means running Grackle without this plugin gives a clean "sessions + environments only" experience with no task DAG.

## Usage

```typescript
import { createCorePlugin } from "@grackle-ai/server/core-plugin";
import { createOrchestrationPlugin } from "@grackle-ai/plugin-orchestration";
import { loadPlugins } from "@grackle-ai/plugin-sdk";

const loaded = await loadPlugins(
  [createCorePlugin(), createOrchestrationPlugin()],
  pluginContext,
);
```

## What This Plugin Contributes

### gRPC Handlers (21 RPCs)

| Group | Methods |
|---|---|
| Tasks | `listTasks`, `createTask`, `getTask`, `updateTask`, `startTask`, `completeTask`, `setWorkpad`, `resumeTask`, `stopTask`, `deleteTask` |
| Personas | `listPersonas`, `createPersona`, `getPersona`, `updatePersona`, `deletePersona` |
| Findings | `postFinding`, `queryFindings`, `getFinding` |
| Escalations | `createEscalation`, `listEscalations`, `acknowledgeEscalation` |

### Reconciliation Phases

- **orphan-reparent** — re-parents child tasks whose parent session has ended

### Event Subscribers

- **sigchld** — handles agent process exit, updates task/session state
- **escalation-auto** — auto-detects and routes escalations to the notification system
- **orphan-reparent** — triggers reparenting on task lifecycle events

## Dependencies

Depends on the `"core"` plugin (declared via `dependencies: ["core"]`).
npm package: @grackle-ai/server
Description: Grackle server orchestrator — spawns and wires core (gRPC), web-server (HTTP), MCP, and PowerLine
Latest version: 0.108.0

# @grackle-ai/server

<p align="center">
  <a href="https://www.npmjs.com/package/@grackle-ai/server"><img src="https://img.shields.io/npm/v/@grackle-ai/server.svg" alt="npm version" /></a>
  <a href="https://github.com/nick-pape/grackle/actions/workflows/ci.yml"><img src="https://github.com/nick-pape/grackle/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI" /></a>
  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT" /></a>
</p>

<p align="center">
  <img src="https://raw.githubusercontent.com/nick-pape/grackle/main/apps/docs-site/static/img/grackle-logo.png" alt="Grackle" width="200" />
</p>

Grackle server orchestrator — spawns and wires together the four subsystems:

1. **Core** (`@grackle-ai/core`) — gRPC business logic
2. **Web Server** (`@grackle-ai/web-server`) — HTTP static files, pairing, OAuth
3. **MCP** (`@grackle-ai/mcp`) — Model Context Protocol server
4. **PowerLine** (`@grackle-ai/powerline`) — local agent runtime manager

## Usage

```bash
# Start the server
node dist/index.js

# Or via CLI
grackle serve
```

The orchestrator handles:
- Database initialization and seeding
- Adapter registration (Docker, SSH, Codespace, Local)
- Local PowerLine auto-start with crash recovery
- gRPC server (HTTP/2) with Bearer token auth
- Web + WebSocket server wiring
- MCP server startup
- Graceful shutdown coordination
npm package: @gradealabs/generator-migrations
Description: A simple migration file generator to more appropriately fit our style
Author: Julia Ricketti
Latest version: 0.0.0
Deprecated: Package is no longer being maintined and will be deleted in January 2020

# generator-migrations [![NPM version][npm-image]][npm-url] [![Build Status][travis-image]][travis-url] [![Dependency Status][daviddm-image]][daviddm-url] [![Coverage percentage][coveralls-image]][coveralls-url]
> A simple migration file generator to more appropriately fit our style

## Installation

First, install [Yeoman](http://yeoman.io) and generator-migrations using [npm](https://www.npmjs.com/) (we assume you have pre-installed [node.js](https://nodejs.org/)).

```bash
npm install -g yo
npm install -g generator-migrations
```

Then generate your new project:

```bash
yo migrations
```

## Getting To Know Yeoman

 * Yeoman has a heart of gold.
 * Yeoman is a person with feelings and opinions, but is very easy to work with.
 * Yeoman can be too opinionated at times but is easily convinced not to be.
 * Feel free to [learn more about Yeoman](http://yeoman.io/).

## License

MIT © [Julia Ricketti]()


[npm-image]: https://badge.fury.io/js/generator-migrations.svg
[npm-url]: https://npmjs.org/package/generator-migrations
[travis-image]: https://travis-ci.org/gradealabs/generator-migrations.svg?branch=master
[travis-url]: https://travis-ci.org/gradealabs/generator-migrations
[daviddm-image]: https://david-dm.org/gradealabs/generator-migrations.svg?theme=shields.io
[daviddm-url]: https://david-dm.org/gradealabs/generator-migrations
[coveralls-image]: https://coveralls.io/repos/gradealabs/generator-migrations/badge.svg
[coveralls-url]: https://coveralls.io/r/gradealabs/generator-migrations
npm package: @gradebook/app-core
Description: > Config and Logging provider for Applications
Author: Vikas Potluri
Latest version: 0.1.2

# `@gradebook/app-core`

> Config and Logging provider for Applications

## Usage

```ts
import {logger, config} from '@gradebook/app-core';

// `config` is an instance of `@gradebook/config`
logger.info(config.get('env'));

// Instance of `@gradebook/logging` - logging config comes via `config.get('logging')`
logger.info('Hello, world!');

// With express
import express from 'express';
// HTTP-related logic is not included in the default export by design
import {useLoggingAndHealthcheck} from '@gradebook/app-core/lib/healthcheck.js';
const app = express();

// Will error if healthcheck is disabled in logging config
// Mounts healthcheck endpoint and adds HTTP request logging to the app
useLoggingAndHealthcheck(app);
```
npm package: @gradebook/client-auth
Description: Authorization management for service:service authentication using a centralized gateway
Author: Vikas Potluri
Latest version: 0.4.0

# `@gradebook/client-auth`

> Authorization management for service:service authentication using a centralized gateway

See [@gradebook/service-auth](https://github.com/gradebook/utils/tree/master/packages/service-auth)

## Usage

```ts
const {AuthManager} = require('@gradebook/client-auth');

const manager = new AuthManager(
	'https://client_id:client_secret@auth.internal/', // Gateway with credentials
	// "buckets" of services that can be used together. This is done to reduce the number of tokens
	// requested from Gateway. e.g. when I talk to Service B, I usually also talk to Service A.
	// This can be as complicated or as simple as you want, but it should include every service
	// the client will use the AuthManager to communicate with
	[
		['group_0_service_a', 'group_0_service_b'],
		['group_1_service_c', 'group_1_service_b'],
	]
);


// Make a request

// The getRequestInfo method is the primary method that will be used. It handles creating a valid JWT and resolving
// the service information.
// Endpoints: POST `${gatewayRoot}/api/v0/token`
//            GET `${gatewayRoot}/api/v0/resolve/:service_name
const [{ip, port, hostname}, fetchOptions] = await manager.getRequestInfo('group_0_service_a');
// We can use `${ip}:${port}` because includeHostInHeader defaults to true - meaning a `host` header is sent along with
// the auth token.
const url = new URL(`${ip}:${port}/api/v0/do-something`/*, {includeHostInHeader: true} */});

const response = await fetch(url.href, fetchOptions).catch(error => {
	// Example: service_a moves to another server. This removes the resolution from the cache
	manager.serviceFailedConnecting('group_0_service_a');
});
```
npm package: @gradebook/core-developer-tools
Description: ## Usage
Author: Vikas Potluri
Latest version: 0.2.2

# `@gradebook/core-developer-tools`

## Usage

```js
// gradebook/server developer.js
module.exports.developerLogic = app => {
	const coreDeveloperTools = require('@gradebook/core-developer-tools');
	coreDeveloperTools.load(__dirname, app);

	// Add your own logic here
};
```

## Why does this package exist?

To aid in development, we have several in-house developer tools. This includes basic things like:
 - asset routing with a local front-end
 - live reloading
 - request delays

We also have more complex use-cases such as bypassing login screens or overriding existing settings.

These complex use cases have security implications, which is why this package exists.

In the server:

1. Developer Tools are not loaded unless the `enableDeveloperExperiments` flag is enabled

1. Developer Tools fail to load in production environments

1. The more complex tools are bundled in this module

   1. It's a development dependency, which means it won't be installed in production

   1. This module does _another_ production check before bootstrapping

1. Developers have to create a `developer.js` file in the server project which loads this module

As you can see, there are several safe-guards in place to make sure these features are not exposed in a production environment.