First stab at a dev server in pub using barback.

pkg/barback/lib/src/barback.dart

+// Copyright (c) 2013, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+library barback.barback;
+
+import 'dart:async';
+
+import 'asset.dart';
+import 'asset_id.dart';
+import 'asset_cascade.dart';
+import 'package_graph.dart';
+import 'package_provider.dart';
+
+/// A general purpose asynchronous build dependency graph manager.

[nweiz, 2013/07/25 22:58:58]

"General purpose" should be hyphenated.

I want a little more description than this about barback's purpose before you
start diving into how to use it. "Build dependency graph manager" can mean a lot
of things. Talk about how it takes assets (including Dart files) from multiple
packages, runs package-specific transformations on them, and tracks when the
transformations need to be re-run.

[Bob Nystrom, 2013/07/26 20:20:11]

Done.

+///
+/// You give barback a [PackageProvider] which can yield a set of [Transformer]s
+/// and raw source [Asset]s. Then you add input files to the system by calling

[nweiz, 2013/07/25 22:58:58]

"input files to the system" is confusing. [updateSources] doesn't actually
provide it with files; it does a sort of combination of telling it which files
exist and when they get updated.

[Bob Nystrom, 2013/07/26 20:20:11]

Done.

+/// [updateSources]. Barback will automatically wire up the appropriate
+/// transformers to those inputs and start running them asynchronously. If the

[nweiz, 2013/07/25 22:58:58]

"the transformer" -> "a transformer"

[Bob Nystrom, 2013/07/26 20:20:11]

Done.

+/// transformer produces outputs that can be consumed by other transformers,
+/// they will automatically be pipelined correctly.
+///
+/// You can then request assets (either source or generated) by calling
+/// [getAssetById]. This will wait for any necessary transformations and then
+/// return the asset.
+///
+/// When source files have been modified or removed, tell barback by calling
+/// [updateSources] and [removeSources] as appropriate. Barback will
+/// automatically track which transformations are affected by those changes and
+/// re-run them as needed.
+///
+/// Barback tries to be resilient to errors since assets are often in an
+/// in-progress state. When errors occur, they will be captured and emitted on
+/// the [errors] stream.
+class Barback {
+  /// The graph managed by this instance.
+  final PackageGraph _graph;
+
+  /// A stream that emits a [BuildResult] each time the build is completed,
+  /// whether or not it succeeded.
+  ///
+  /// This will emit a result only once every package's [AssetCascade] has
+  /// finished building.
+  ///
+  /// If an unexpected error in barback itself occurs, it will be emitted
+  /// through this stream's error channel.
+  Stream<BuildResult> get results => _graph.results;
+
+  /// A stream that emits any errors from the graph or the transformers.
+  ///
+  /// This emits errors as they're detected. If an error occurs in one part of
+  /// the graph, unrelated parts will continue building.
+  ///
+  /// This will not emit programming errors from barback itself. Those will be
+  /// emitted through the [results] stream's error channel.
+  Stream get errors => _graph.errors;
+
+  Barback(PackageProvider provider)
+      : _graph = new PackageGraph(provider);
+
+  /// Gets the asset identified by [id].
+  ///
+  /// If [id] is for a generated or transformed asset, this will wait until
+  /// it has been created and return it. If the asset cannot be found, throws
+  /// [AssetNotFoundException].
+  Future<Asset> getAssetById(AssetId id) => _graph.getAssetById(id);
+
+  /// Adds [sources] to the graph's known set of source assets.
+  ///
+  /// Begins applying any transforms that can consume any of the sources. If a
+  /// given source is already known, it is considered modified and all
+  /// transforms that use it will be re-applied.
+  void updateSources(Iterable<AssetId> sources) =>
+      _graph.updateSources(sources);
+
+  /// Removes [removed] from the graph's known set of source assets.
+  void removeSources(Iterable<AssetId> removed) =>
+      _graph.removeSources(removed);
+}