Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/calm-caches-report.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'rock': patch
---

Add `remote-cache status` for checking whether the current native fingerprint has a matching GitHub Actions or S3 remote build artifact.
30 changes: 30 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
# AGENTS.md

Rock is a modular React Native CLI. `packages/config` loads project configuration and
creates the `PluginApi`; platform, bundler, and utility plugins register commands through it.

## Architecture

- Platform logic is encapsulated in `packages/platform-*`; projects add platforms dynamically
through configuration. Core code must use `PluginApi`, not hard-code platform implementations.
- Shared Apple implementation belongs in `packages/platform-apple-helpers`.
- `packages/tools` owns cross-package contracts, fingerprinting, caching, logging, and process helpers.
- Keep shared command behavior provider- and platform-agnostic; specialize at package boundaries.
- `plugin-metro`'s `start` and `bundle` commands are ports of React Native's community CLI plugin;
diff their upstream sources on every React Native upgrade, especially Metro handling.
- Runtime packages remain compatible with older React Native and Metro APIs; the default template
instead tracks the latest available React Native. Do not infer runtime minimums from template deps.
- `templates/rock-template-default` follows the Community CLI template but is not a verbatim mirror;
platform and bundler packages contribute additional template fragments.
- `create-rock` migrates existing Community CLI projects; preserve drop-in behavior unless a
difference is intentional and documented.

## Release rules

- For the current 0.x line, use a patch Changeset unless adding support for a new React Native version.
- Changesets version `@rock-js/*`, `rock`, and `create-rock` together as a fixed group.

## Validation

- Test and typecheck the affected package first.
- Run `pnpm build` for cross-package API or contract changes.
179 changes: 179 additions & 0 deletions packages/cli/src/lib/plugins/__tests__/remoteCache.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,179 @@
import type {
FingerprintOptions,
RemoteArtifact,
RemoteBuildCache,
} from '@rock-js/tools';
import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
import { remoteCache } from '../remoteCache.js';

const fingerprint = '7af554b93cd696ca95308fdebe3a4484001bb7b4';
const artifactName = `rock-android-Adhoc-${fingerprint}`;
const fingerprintOptions: FingerprintOptions = {
extraSources: [],
ignorePaths: [],
env: [],
};

const formatArtifactName = vi.hoisted(() => vi.fn());

vi.mock('@rock-js/tools', async (importOriginal) => {
const original = await importOriginal();
return {
...(original as Record<string, unknown>),
formatArtifactName,
};
});

function createRemoteCacheProvider(artifacts: RemoteArtifact[], name = 'S3') {
const list = vi.fn().mockResolvedValue(artifacts);
const remoteBuildCache: RemoteBuildCache = {
name,
list,
download: vi.fn(),
delete: vi.fn(),
upload: vi.fn(),
};

return {
list,
remoteCacheProvider: () => remoteBuildCache,
};
}

beforeEach(() => {
formatArtifactName.mockResolvedValue(artifactName);
vi.spyOn(console, 'log').mockImplementation(() => {});
});

afterEach(() => {
vi.restoreAllMocks();
});

describe('remote-cache status', () => {
describe.each(['GitHub', 'S3'])('%s provider', (providerName) => {
test('reports a cache hit as JSON', async () => {
const artifact = {
name: artifactName,
url: 'https://example.com/artifact.zip',
};
const { list, remoteCacheProvider } = createRemoteCacheProvider(
[artifact],
providerName,
);

await remoteCache({
action: 'status',
args: {
platform: 'android',
traits: ['Adhoc'],
json: true,
},
remoteCacheProvider,
projectRoot: '/project',
fingerprintOptions,
});

expect(list).toHaveBeenCalledWith({ artifactName, limit: 1 });
expect(console.log).toHaveBeenCalledWith(
JSON.stringify(
{
provider: providerName,
fingerprint,
artifactName,
hit: true,
artifact,
},
null,
2,
),
);
});

test('reports a cache miss as JSON', async () => {
const { remoteCacheProvider } = createRemoteCacheProvider(
[],
providerName,
);

await remoteCache({
action: 'status',
args: {
platform: 'android',
traits: ['Adhoc'],
json: true,
},
remoteCacheProvider,
projectRoot: '/project',
fingerprintOptions,
});

expect(console.log).toHaveBeenCalledWith(
JSON.stringify(
{
provider: providerName,
fingerprint,
artifactName,
hit: false,
artifact: null,
},
null,
2,
),
);
});
});

test('returns when no remote cache provider is configured', async () => {
await expect(
remoteCache({
action: 'status',
args: {
platform: 'android',
traits: ['Adhoc'],
json: true,
},
remoteCacheProvider: null,
projectRoot: '/project',
fingerprintOptions,
}),
).resolves.toBeNull();
});

test('propagates provider lookup failures', async () => {
const { list, remoteCacheProvider } = createRemoteCacheProvider([]);
list.mockRejectedValueOnce(new Error('S3 is unavailable'));

await expect(
remoteCache({
action: 'status',
args: {
platform: 'android',
traits: ['Adhoc'],
json: true,
},
remoteCacheProvider,
projectRoot: '/project',
fingerprintOptions,
}),
).rejects.toThrow('S3 is unavailable');
});

test('requires platform and traits', async () => {
const { remoteCacheProvider } = createRemoteCacheProvider([]);

await expect(
remoteCache({
action: 'status',
args: {
name: artifactName,
json: true,
},
remoteCacheProvider,
projectRoot: '/project',
fingerprintOptions,
}),
).rejects.toThrow(
'The "status" action requires "--platform" and "--traits".',
);
});
});
49 changes: 45 additions & 4 deletions packages/cli/src/lib/plugins/remoteCache.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,11 @@ import fs from 'node:fs';
import os from 'node:os';
import path from 'node:path';
import type { PluginApi, PluginOutput } from '@rock-js/config';
import type { FingerprintOptions, RemoteBuildCache } from '@rock-js/tools';
import type {
FingerprintOptions,
RemoteArtifact,
RemoteBuildCache,
} from '@rock-js/tools';
import {
color,
colorLink,
Expand Down Expand Up @@ -37,7 +41,15 @@ type Flags = {
adHoc?: boolean;
};

async function remoteCache({
type RemoteCacheStatus = {
provider: string;
fingerprint: string;
artifactName: string;
hit: boolean;
artifact: RemoteArtifact | null;
};

export async function remoteCache({
action,
args,
remoteCacheProvider,
Expand Down Expand Up @@ -96,6 +108,30 @@ async function remoteCache({
}
break;
}
case 'status': {
const artifact = (
await remoteBuildCache.list({ artifactName, limit: 1 })
)[0];
const artifactNamePrefix = `rock-${args.platform}-${args.traits?.join('-')}-`;
const status: RemoteCacheStatus = {
provider: remoteBuildCache.name,
fingerprint: artifactName.slice(artifactNamePrefix.length),
artifactName,
hit: artifact !== undefined,
artifact: artifact ?? null,
};

if (isJsonOutput) {
console.log(JSON.stringify(status, null, 2));
} else {
logger.log(`Remote cache status:
- provider: ${color.bold(remoteBuildCache.name)}
- fingerprint: ${color.bold(color.magenta(status.fingerprint))}
- artifact: ${color.bold(color.blue(artifactName))}
- status: ${status.hit ? color.green('hit') : color.yellow('miss')}`);
}
break;
}
case 'list-all': {
const artifactName = undefined;
const artifacts = await remoteBuildCache.list({ artifactName });
Expand Down Expand Up @@ -457,7 +493,12 @@ function validateArgs(args: Flags, action: string) {
if (!action) {
// @todo make Commander handle this
throw new RockError(
'Action is required. Available actions: list, list-all, download, upload, delete',
'Action is required. Available actions: list, status, list-all, download, upload, delete, get-provider-name',
);
}
if (action === 'status' && (!args.platform || !args.traits)) {
throw new RockError(
'The "status" action requires "--platform" and "--traits".',
);
}
if (action === 'list-all' || action === 'get-provider-name') {
Expand Down Expand Up @@ -503,7 +544,7 @@ export const remoteCachePlugin =
{
name: '[action]',
description:
'Select action, e.g. list, list-all, download, upload, delete, get-provider-name',
'Select action, e.g. list, status, list-all, download, upload, delete, get-provider-name',
},
],
options: [
Expand Down
13 changes: 13 additions & 0 deletions website/src/docs/cli/introduction.md
Original file line number Diff line number Diff line change
Expand Up @@ -424,6 +424,7 @@ Available actions:
| Action | Description |
| :------------------ | :-------------------------------------------------------------------------------- |
| `list` | Lists the latest artifact matching the specified criteria |
| `status` | Reports whether the current fingerprint has a matching cached artifact |
| `list-all` | Lists all artifacts (optionally filtered by platform and traits) |
| `download` | Downloads an artifact from remote cache to local cache |
| `upload` | Uploads a binary to remote cache. Accepts `--ad-hoc` flag for Ad-Hoc distribution |
Expand Down Expand Up @@ -455,6 +456,18 @@ or pass `--traits`, so you don't need to pass the fingerprint:
npx rock remote-cache download --platform ios --traits simulator,Release
```

To check whether the current fingerprint has a matching cached artifact without
downloading it:

```shell
npx rock remote-cache status --platform ios --traits device,AdHoc --json
```

The JSON output includes the provider, fingerprint, artifact name, hit status,
and matching artifact information when one exists. It supports both bundled
remote cache providers: GitHub Actions and S3 (including S3-compatible
storage). The command fails when the provider lookup fails.

#### Ad-hoc distribution

Ad-hoc distribution allows you to share your mobile app with testers without going through the App Store or Play Store. Testers can install your app directly on their devices by visiting a web page.
Expand Down
Loading